From 1ee59a38b7c873071d8a06adbceb2cb674118543 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Mon, 6 Jul 2026 08:10:48 +0000
Subject: [PATCH 1/9] Add warm-sandbox-pool example

Demonstrates maintaining a pool of pre-initialized warm sandboxes
for Ruby-based applications, eliminating startup delays by
late-binding conversations to prepared sandboxes.

Features:
- Pre-initialized sandboxes with Ruby/Sinatra already running
- Automatic pool refill when sandboxes are consumed
- Web UI for monitoring pool status and starting conversations
- Alternative to custom images using OpenHands Cloud APIs

Recovered from conversation 4c1947abfc4f4ed6ba76d9b4c7324d8f

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/.gitignore                  |  14 +
 warm-sandbox-pool/QUICKSTART.md               | 226 ++++++++
 warm-sandbox-pool/README.md                   | 342 ++++++++++++
 warm-sandbox-pool/pool_controller.py          | 515 ++++++++++++++++++
 warm-sandbox-pool/pyproject.toml              |  18 +
 warm-sandbox-pool/requirements.txt            |   3 +
 .../sandbox_prep/init_ruby_service.sh         | 139 +++++
 .../sandbox_prep/quote_service.rb             |  80 +++
 warm-sandbox-pool/static/app.js               | 253 +++++++++
 warm-sandbox-pool/static/styles.css           | 458 ++++++++++++++++
 warm-sandbox-pool/templates/index.html        | 135 +++++
 warm-sandbox-pool/test_structure.py           |  80 +++
 12 files changed, 2263 insertions(+)
 create mode 100644 warm-sandbox-pool/.gitignore
 create mode 100644 warm-sandbox-pool/QUICKSTART.md
 create mode 100644 warm-sandbox-pool/README.md
 create mode 100644 warm-sandbox-pool/pool_controller.py
 create mode 100644 warm-sandbox-pool/pyproject.toml
 create mode 100644 warm-sandbox-pool/requirements.txt
 create mode 100644 warm-sandbox-pool/sandbox_prep/init_ruby_service.sh
 create mode 100644 warm-sandbox-pool/sandbox_prep/quote_service.rb
 create mode 100644 warm-sandbox-pool/static/app.js
 create mode 100644 warm-sandbox-pool/static/styles.css
 create mode 100644 warm-sandbox-pool/templates/index.html
 create mode 100644 warm-sandbox-pool/test_structure.py

diff --git a/warm-sandbox-pool/.gitignore b/warm-sandbox-pool/.gitignore
new file mode 100644
index 0000000..bd53561
--- /dev/null
+++ b/warm-sandbox-pool/.gitignore
@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+*.egg-info/
+dist/
+build/
+.DS_Store
+*.log
+.env
diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
new file mode 100644
index 0000000..1cc45c6
--- /dev/null
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -0,0 +1,226 @@
+# Quick Start Guide
+
+Get the Warm Sandbox Pool demo running in 5 minutes.
+
+## Prerequisites
+
+- **OpenHands Cloud API Key** - Get one from https://app.all-hands.dev
+- **Python 3.10+** - Check with `python --version`
+- **Git** - To clone this repository
+
+## Installation (30 seconds)
+
+```bash
+# Clone the repository
+git clone https://github.com/jpshackelford/oh-examples.git
+cd oh-examples/warm-sandbox-pool
+
+# Install Python dependencies (use uv or pip)
+pip install -r requirements.txt
+
+# Or with uv (faster)
+uv pip install -e .
+```
+
+## Run the Demo (10 seconds)
+
+```bash
+# Set your API key
+export OH_API_KEY=your_api_key_here
+
+# Start the pool controller
+python pool_controller.py
+
+# You should see:
+# INFO pool_controller: Pool controller initialized: size=3, threshold=2
+# INFO pool_controller: Pool manager thread started
+# INFO pool_controller: Starting web server on port 5000
+# INFO pool_controller: Open http://localhost:5000 in your browser
+```
+
+## Use the Demo (2-3 minutes)
+
+1. **Open http://localhost:5000** in your browser
+
+2. **Watch the pool initialize**:
+   - You'll see "Preparing pool..." message
+   - 3 sandboxes will start initializing (takes ~30-60 seconds each)
+   - Watch them progress: 🔴 STARTING → 🟡 PREPARING → 🟢 READY
+
+3. **Start a conversation**:
+   - Once at least one sandbox is READY, the conversation UI appears
+   - Type a message or use the default:
+     ```
+     Check if the quote service is running on localhost:4567 and fetch me a random quote.
+     ```
+   - Click "🚀 Start Conversation"
+
+4. **Observe the magic**:
+   - A ready sandbox is instantly pulled from the pool
+   - OpenHands conversation starts immediately (no wait!)
+   - Click the conversation link to see your agent working
+   - Watch the pool automatically provision a new sandbox to refill
+
+## What's Happening?
+
+```
+Before (Without Warm Pool):
+User clicks "Start" → Wait 30-60s for sandbox → Agent starts
+                       ⏳ User sees delay
+
+With Warm Pool:
+User clicks "Start" → Instant sandbox → Agent starts
+                       ⚡ No apparent delay
+                       (Pool refills in background)
+```
+
+## Try These Commands in Your Conversation
+
+Once your conversation is attached to a warm sandbox:
+
+```
+"Show me the Ruby version installed"
+→ Should show Ruby 3.x already installed
+
+"Check if the quote service is running on port 4567"
+→ Should show it's already running
+
+"Fetch a quote from localhost:4567/quote and show it to me"
+→ Should return a programming quote from the API
+
+"Get all quotes from localhost:4567/quotes and count them"
+→ Should list 8 quotes
+
+"Find quotes by Martin Fowler using the API"
+→ Should search the quotes service
+```
+
+## Next Steps
+
+### For Demo/Learning
+- Experiment with different pool sizes: `POOL_SIZE=5 python pool_controller.py`
+- Watch the auto-refill behavior by starting multiple conversations
+- Check the sandbox init logs in the web UI
+
+### For Custom Application Deployment
+1. **Customize** `sandbox_prep/init_ruby_service.sh` with your application setup
+2. **Test** the initialization manually before running the full pool
+3. **Adjust** pool size and timing parameters for your needs
+4. **Deploy** your adapted pool controller
+
+## Configuration
+
+Customize via environment variables:
+
+```bash
+# Basic config
+export OH_API_KEY=your_key
+export OH_API_BASE=https://app.all-hands.dev  # or your instance
+export PORT=5000                               # Web UI port
+
+# Pool sizing
+export POOL_SIZE=3          # How many ready sandboxes to maintain
+export POOL_THRESHOLD=2     # Start refilling when ready count drops below this
+
+# Sandbox config (optional)
+export SANDBOX_SPEC_ID=your_spec_id  # Use custom runtime image
+```
+
+## Troubleshooting
+
+### "No ready sandboxes available" error
+- **Wait longer**: Initial pool fill takes 1-3 minutes
+- **Check API key**: Make sure `OH_API_KEY` is valid
+- **View logs**: Look at terminal output for error messages
+- **Check web UI**: Look for FAILED sandboxes and error messages
+
+### Sandboxes stuck in PREPARING
+- **Check init script**: May be timing out or failing
+- **Increase timeout**: Set higher init timeout in code
+- **Test manually**: Use `start-sandbox/` example to debug
+
+### "OH_API_KEY is required" error
+```bash
+# Set your API key before running
+export OH_API_KEY=your_actual_key_here
+python pool_controller.py
+```
+
+### Port already in use
+```bash
+# Use a different port
+PORT=8080 python pool_controller.py
+```
+
+## Architecture at a Glance
+
+```
+┌─────────────────┐
+│  Browser (You)  │
+└────────┬────────┘
+         │ http://localhost:5000
+         ▼
+┌─────────────────────────┐
+│ Flask Web Server        │
+│ - Serves UI             │
+│ - REST API              │
+│ - SSE for real-time     │
+└────────┬────────────────┘
+         │
+         ▼
+┌─────────────────────────┐
+│ Pool Controller         │
+│ - Manages 3 sandboxes   │
+│ - Auto-refills pool     │
+│ - Attaches conversations│
+└────────┬────────────────┘
+         │
+    ┌────┴────┬────────┐
+    ▼         ▼        ▼
+┌────────┐ ┌────────┐ ┌────────┐
+│Sandbox1│ │Sandbox2│ │Sandbox3│
+│ Ruby ✓ │ │ Ruby ✓ │ │ Ruby ✓ │
+│ Gems ✓ │ │ Gems ✓ │ │ Gems ✓ │
+│Service✓│ │Service✓│ │Service✓│
+│ READY  │ │ READY  │ │ READY  │
+└────────┘ └────────┘ └────────┘
+```
+
+## Files Overview
+
+```
+warm-sandbox-pool/
+├── README.md                      📖 Comprehensive documentation
+├── QUICKSTART.md                  ⚡ This file - get started fast
+├── pool_controller.py             🎛️  Main backend (Flask + pool logic)
+├── requirements.txt               📦 Python dependencies
+├── pyproject.toml                 📦 UV-compatible project config
+├── sandbox_prep/
+│   ├── init_ruby_service.sh      🔧 Demo: Ruby/Sinatra init
+│   └── quote_service.rb          💎 Demo Ruby service
+├── static/
+│   ├── app.js                    🎨 Frontend JavaScript
+│   └── styles.css                🎨 UI styling
+└── templates/
+    └── index.html                📄 Web UI template
+```
+
+## Getting Help
+
+- **Documentation**: Read `README.md` for full details
+- **Example Code**: All files are heavily commented
+- **Related Examples**: Check `../start-sandbox/` and `../clone-and-attach/`
+
+## Success Criteria
+
+You've successfully run the demo when:
+
+✅ Pool shows 3 sandboxes in READY state  
+✅ You can start a conversation and get instant allocation  
+✅ The conversation link opens in OpenHands  
+✅ The agent can interact with the pre-installed quote service  
+✅ Pool automatically provisions a replacement sandbox  
+
+**Total time from zero to working demo: ~5 minutes**
+
+Now you understand how warm sandbox pools work and can adapt this technique for your own application deployment!
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
new file mode 100644
index 0000000..a638f5f
--- /dev/null
+++ b/warm-sandbox-pool/README.md
@@ -0,0 +1,342 @@
+# Warm Sandbox Pool
+
+Demonstrates maintaining a pool of pre-initialized "warm" sandboxes that late-bind to conversations on demand, eliminating startup delays for end users.
+
+**This example demonstrates a technique for deploying Ruby-based applications** using OpenHands Cloud APIs, showing that custom images are not the only viable approach for handling initialization that takes more than a few seconds.
+
+## Context: Alternative to Custom Images
+
+When applications have components that run outside the agent control loop and must be available on the system where the agent is running, a custom image is not the only mechanism for packaging these dependencies. 
+
+Even when using custom images in OpenHands Enterprise, some scenarios require additional tasks to be completed on the running sandbox to make it ready for use. **If these tasks take more than a few seconds, the Warm Sandbox Pool technique eliminates the apparent delay an end-user would see** by preparing a pool of pre-initialized sandboxes that late-bind to conversations when an end-user begins to interact with the agent.
+
+This same approach can be used to install and prepare application services in sandboxes via API calls available in the OpenHands SaaS/Cloud platform, providing a viable alternative to custom images for your deployment needs.
+
+## Concept
+
+Instead of waiting for sandbox provisioning and initialization every time a user starts a conversation, this approach:
+
+1. **Maintains a pool** of pre-initialized sandboxes (e.g., 3 sandboxes)
+2. **Pre-installs dependencies** (Ruby, gems, application services) during sandbox preparation
+3. **Late-binds conversations** - when a user needs a sandbox, one is pulled from the pool instantly
+4. **Auto-refills** - when pool drops below threshold, new sandboxes are automatically provisioned and prepared in the background
+
+This is particularly valuable when:
+- Setup tasks take more than a few seconds (installing Ruby, gems, starting services)
+- You want consistent, fast conversation startup times
+- You need services running and ready before the agent starts working
+- You're using the OpenHands SaaS/Cloud platform without custom images
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Web UI                              │
+├──────────────────────────┬──────────────────────────────────┤
+│   Pool Visualization     │    Conversation Interface        │
+│                          │                                  │
+│  🟢 Sandbox 1: READY     │  [Waiting for pool to be ready]  │
+│  🟡 Sandbox 2: PREPARING │                                  │
+│  🔴 Sandbox 3: STARTING  │  [Then: conversation input box]  │
+└──────────────────────────┴──────────────────────────────────┘
+                           │
+                           ▼
+              ┌────────────────────────┐
+              │   Pool Controller      │
+              │   (Flask Backend)      │
+              └────────────────────────┘
+                           │
+        ┌──────────────────┼──────────────────┐
+        ▼                  ▼                  ▼
+  ┌──────────┐      ┌──────────┐      ┌──────────┐
+  │ Sandbox  │      │ Sandbox  │      │ Sandbox  │
+  │ (READY)  │      │ (READY)  │      │ (READY)  │
+  └──────────┘      └──────────┘      └──────────┘
+       │                 │                 │
+       └─────────────────┴─────────────────┘
+                         │
+              Each sandbox has Ruby +
+              Sinatra gem + demo service
+```
+
+## Demo Application: Ruby Sinatra Service
+
+This example installs a Ruby/Sinatra web service in each sandbox to demonstrate the warm pool technique in a realistic scenario. **The Sinatra service demonstrates how Ruby-based systems** can be installed and running before agent conversations begin.
+
+The initialization process (installing Ruby runtime, gems, starting the service) shows how to deploy application services using the same API-driven preparation approach for your specific use case.
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- OpenHands Cloud API key (`OH_API_KEY`)
+- `uv` or standard Python environment
+
+### Installation
+
+```bash
+# Install dependencies
+uv pip install -e .
+
+# Or with pip
+pip install -r requirements.txt
+```
+
+### Run the Demo
+
+```bash
+export OH_API_KEY=your_api_key_here
+python pool_controller.py
+```
+
+Then open http://localhost:5000 in your browser.
+
+### What You'll See
+
+1. **Initial State**: "Preparing pool..." message while 3 sandboxes initialize
+2. **Pool Visualization**: Real-time status of each sandbox:
+   - 🔴 **STARTING**: OpenHands is provisioning the sandbox
+   - 🟡 **PREPARING**: Installing Ruby, gems, starting service
+   - 🟢 **READY**: Fully initialized and available
+3. **Conversation UI**: Once pool is ready, type a message to start a conversation
+4. **Sandbox Allocation**: A ready sandbox is pulled from the pool and attached to your conversation
+5. **Auto-Refill**: Watch as a new sandbox automatically begins initializing to refill the pool
+
+### Configuration
+
+Environment variables:
+
+- `OH_API_KEY`: OpenHands Cloud API key (required)
+- `OH_API_BASE`: API base URL (default: `https://app.all-hands.dev`)
+- `POOL_SIZE`: Target pool size (default: `3`)
+- `POOL_THRESHOLD`: Trigger refill when pool drops below this (default: `2`)
+- `PORT`: Web server port (default: `5000`)
+
+### Testing the Ruby Service
+
+Once a sandbox is in READY state, the Sinatra service is running on port 4567. You can test it:
+
+```bash
+# Get the sandbox ID from the web UI, then:
+curl https://work-1-<sandbox-slug>.prod-runtime.all-hands.dev:12000/quote
+```
+
+Or ask the agent to interact with it:
+```
+"Call the quote service running on localhost:4567 and show me today's quote"
+```
+
+## Implementation Details
+
+### Sandbox Initialization Process
+
+Each sandbox goes through these preparation steps (see `sandbox_prep/init_ruby_service.sh`):
+
+1. **Install Ruby**: Uses rbenv to install Ruby 3.2
+2. **Install Sinatra**: Gem install sinatra
+3. **Deploy Service**: Copies the quote service code
+4. **Start Service**: Launches the Sinatra app in the background
+5. **Verify**: Confirms the service responds to health checks
+
+This simulates a realistic scenario where your agent needs specific tools/services pre-installed.
+
+### Pool Management
+
+The `PoolController` class handles:
+
+- **Provisioning**: Creates sandboxes via OpenHands Cloud API
+- **Monitoring**: Polls sandbox status until RUNNING
+- **Initialization**: Executes preparation scripts via agent-server API
+- **Queue Management**: Thread-safe queue of ready sandboxes
+- **Auto-Refill**: Background thread maintains pool size
+- **Conversation Binding**: Attaches conversations to pre-warmed sandboxes
+
+### Real-Time Updates
+
+The web UI uses Server-Sent Events (SSE) to stream pool state updates in real-time without polling.
+
+## Files
+
+```
+warm-sandbox-pool/
+├── README.md                          # This file
+├── pool_controller.py                 # Flask backend + pool manager
+├── requirements.txt                   # Python dependencies
+├── sandbox_prep/
+│   ├── init_ruby_service.sh          # Bash script to initialize each sandbox
+│   └── quote_service.rb              # Ruby/Sinatra demo service
+├── static/
+│   ├── app.js                        # Frontend JavaScript
+│   └── styles.css                    # UI styling
+└── templates/
+    └── index.html                    # Main web page
+```
+
+## Use Cases
+
+### 1. Custom Runtime Environments
+
+Pre-install language runtimes (Ruby, Java, Go) that take time to set up:
+
+```bash
+# In init script
+rbenv install 3.2.0
+rbenv global 3.2.0
+gem install rails bundler
+```
+
+### 2. Service Dependencies
+
+Start databases, caches, or mock APIs before the agent runs:
+
+```bash
+# In init script
+docker run -d -p 5432:5432 postgres
+redis-server --daemonize yes
+./mock-api-server &
+```
+
+### 3. Large Codebases
+
+Clone and prepare large repositories with dependencies:
+
+```bash
+# In init script
+git clone --depth 1 https://github.com/your-org/monorepo /workspace/project
+cd /workspace/project
+bundle install
+npm install
+make build
+```
+
+### 4. Custom Application Integration
+
+Replace the demo Sinatra service with your actual application initialization:
+
+```bash
+# In init script (replace sandbox_prep/init_ruby_service.sh contents)
+# Install Ruby (or use a runtime that already has it)
+rbenv install 3.2.0
+rbenv global 3.2.0
+
+# Install your application gems
+gem install your_gem_name
+
+# Initialize your application
+cd /workspace
+# ... your app-specific setup commands
+bundle install
+
+# Start your services in daemon mode
+rails server -d -p 4567
+
+# Wait for service to be ready
+until curl -f http://localhost:4567/health; do
+    echo "Waiting for application..."
+    sleep 2
+done
+
+echo "✅ Application ready"
+```
+
+By pre-warming sandboxes with your application already running, agents can immediately interact with your services without the 30-60 second initialization delay on every conversation start.
+
+## Benefits vs. Custom Images
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Custom Images** | Fastest cold start, baked-in dependencies | Requires OpenHands Enterprise, image build pipeline, version management |
+| **Warm Sandbox Pool** | Works on SaaS, flexible initialization, no image builds | Requires pool management code, higher resource usage |
+| **Just-in-Time Init** | Simplest code, minimal resources | Slow user experience, wait time on every conversation |
+
+**Warm Sandbox Pool is ideal when**:
+- You're on OpenHands SaaS/Cloud (custom images not available)
+- Setup time is 10-60 seconds (too slow for UX, too fast to justify custom image complexity)
+- You want flexibility to change initialization without rebuilding images
+- You have predictable conversation volume
+
+## Extending the Example
+
+### Add More Preparation Steps
+
+Edit `sandbox_prep/init_ruby_service.sh` to install additional tools:
+
+```bash
+# Install Node.js
+curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+apt-get install -y nodejs
+
+# Install Python packages
+pip install pandas numpy jupyter
+```
+
+### Customize the Demo Service
+
+Replace `sandbox_prep/quote_service.rb` with your own Ruby application or gem.
+
+### Adjust Pool Parameters
+
+```python
+# In pool_controller.py
+POOL_SIZE = 5              # Maintain 5 ready sandboxes
+POOL_THRESHOLD = 3         # Refill when below 3
+INIT_TIMEOUT = 600         # Allow 10 minutes for initialization
+```
+
+### Add Health Checks
+
+Extend the initialization to verify services are actually ready:
+
+```bash
+# In init script
+until curl -f http://localhost:4567/health; do
+    echo "Waiting for service..."
+    sleep 2
+done
+```
+
+## Troubleshooting
+
+### Pool Never Reaches Ready State
+
+Check the initialization logs in the web UI. Common issues:
+- Ruby installation timeout (increase `INIT_TIMEOUT`)
+- Network issues downloading gems
+- Insufficient sandbox resources
+
+### Sandboxes Get Stuck in PREPARING
+
+Look at the agent-server command output. The init script may be failing. Test it manually:
+
+```bash
+# Get a sandbox URL from the UI, then:
+curl -X POST https://<agent-server-url>/api/bash/execute_bash_command \
+  -H "X-Session-API-Key: <session-key>" \
+  -d '{"command": "bash /workspace/init_ruby_service.sh", "timeout": 300}'
+```
+
+### High Resource Usage
+
+Reduce `POOL_SIZE` or implement smarter pool management:
+- Scale pool size based on time of day
+- Implement idle timeout (destroy sandboxes after 30 min unused)
+- Use pool only for peak hours, fall back to JIT otherwise
+
+## Next Steps
+
+1. **Production Deployment**: Add error handling, logging, metrics
+2. **Persistent Storage**: Save pool state to Redis/database for crash recovery
+3. **Multi-Tenant**: Separate pools per user/organization
+4. **Dynamic Scaling**: Adjust pool size based on demand
+5. **Cost Optimization**: Implement sandbox recycling (reset instead of destroy)
+
+## Related Examples
+
+- `start-sandbox/` - Basic sandbox provisioning
+- `clone-and-attach/` - Conversation attachment patterns
+- `upload-skills/` - Pre-loading agent skills
+
+## License
+
+MIT - See repository root LICENSE file
diff --git a/warm-sandbox-pool/pool_controller.py b/warm-sandbox-pool/pool_controller.py
new file mode 100644
index 0000000..725d1aa
--- /dev/null
+++ b/warm-sandbox-pool/pool_controller.py
@@ -0,0 +1,515 @@
+#!/usr/bin/env python3
+"""
+Warm Sandbox Pool Controller
+
+Maintains a pool of pre-initialized OpenHands sandboxes with Ruby/Sinatra services
+already running. When users start conversations, sandboxes are pulled from the pool
+and attached instantly, with automatic refill.
+
+Usage:
+    export OH_API_KEY=your_key_here
+    python pool_controller.py
+
+Then open http://localhost:5000 in your browser.
+"""
+
+import argparse
+import json
+import logging
+import os
+import queue
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import requests
+from flask import Flask, jsonify, render_template, request
+from flask_cors import CORS
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("pool_controller")
+
+
+class SandboxState(str, Enum):
+    """States a sandbox progresses through in the pool."""
+
+    STARTING = "STARTING"  # OpenHands provisioning the sandbox
+    PREPARING = "PREPARING"  # Running initialization script
+    READY = "READY"  # Fully initialized and available
+    ALLOCATED = "ALLOCATED"  # Pulled from pool and attached to conversation
+    FAILED = "FAILED"  # Initialization failed
+
+
+@dataclass
+class PooledSandbox:
+    """Represents a sandbox in the pool with its current state."""
+
+    id: str
+    state: SandboxState
+    agent_url: str | None = None
+    session_api_key: str | None = None
+    created_at: datetime = field(default_factory=datetime.now)
+    ready_at: datetime | None = None
+    allocated_at: datetime | None = None
+    conversation_id: str | None = None
+    error_message: str | None = None
+    init_log: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "state": self.state.value,
+            "agent_url": self.agent_url,
+            "created_at": self.created_at.isoformat(),
+            "ready_at": self.ready_at.isoformat() if self.ready_at else None,
+            "allocated_at": self.allocated_at.isoformat() if self.allocated_at else None,
+            "conversation_id": self.conversation_id,
+            "error_message": self.error_message,
+            "init_log": self.init_log[-10:],  # Last 10 log lines
+        }
+
+
+class PoolController:
+    """Manages a pool of warm OpenHands sandboxes."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        pool_size: int = 3,
+        threshold: int = 2,
+        sandbox_spec_id: str | None = None,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.pool_size = pool_size
+        self.threshold = threshold
+        self.sandbox_spec_id = sandbox_spec_id
+
+        self.headers = {"X-Session-API-Key": api_key}
+        self.ready_queue: queue.Queue[PooledSandbox] = queue.Queue()
+        self.all_sandboxes: dict[str, PooledSandbox] = {}
+        self.lock = threading.RLock()
+        self.running = True
+
+        # Load initialization script
+        self.init_script = self._load_init_script()
+
+        logger.info(
+            f"Pool controller initialized: size={pool_size}, threshold={threshold}"
+        )
+
+    def _load_init_script(self) -> str:
+        """Load the sandbox initialization script."""
+        script_path = Path(__file__).parent / "sandbox_prep" / "init_ruby_service.sh"
+        if not script_path.exists():
+            raise FileNotFoundError(f"Init script not found: {script_path}")
+        return script_path.read_text()
+
+    def start(self) -> None:
+        """Start the pool management background thread."""
+        thread = threading.Thread(target=self._pool_manager_loop, daemon=True)
+        thread.start()
+        logger.info("Pool manager thread started")
+
+    def _pool_manager_loop(self) -> None:
+        """Background thread that maintains the pool at the target size."""
+        # Initial fill
+        logger.info(f"Initial pool fill to {self.pool_size} sandboxes")
+        for _ in range(self.pool_size):
+            self._provision_sandbox()
+
+        # Maintenance loop
+        while self.running:
+            time.sleep(5)
+            ready_count = self.ready_queue.qsize()
+            if ready_count < self.threshold:
+                needed = self.pool_size - self._total_initializing_count() - ready_count
+                if needed > 0:
+                    logger.info(
+                        f"Pool below threshold ({ready_count} < {self.threshold}), "
+                        f"provisioning {needed} sandbox(es)"
+                    )
+                    for _ in range(needed):
+                        self._provision_sandbox()
+
+    def _total_initializing_count(self) -> int:
+        """Count sandboxes currently initializing (STARTING or PREPARING)."""
+        with self.lock:
+            return sum(
+                1
+                for sb in self.all_sandboxes.values()
+                if sb.state in (SandboxState.STARTING, SandboxState.PREPARING)
+            )
+
+    def _provision_sandbox(self) -> None:
+        """Start provisioning a new sandbox (runs in background thread)."""
+        thread = threading.Thread(target=self._provision_and_init_sandbox, daemon=True)
+        thread.start()
+
+    def _provision_and_init_sandbox(self) -> None:
+        """Provision, initialize, and add a sandbox to the ready queue."""
+        sandbox = None
+        try:
+            # 1. Create sandbox via Cloud API
+            logger.info("Creating new sandbox...")
+            params = {"sandbox_spec_id": self.sandbox_spec_id} if self.sandbox_spec_id else None
+            resp = requests.post(
+                f"{self.base_url}/api/v1/sandboxes", headers=self.headers, params=params, timeout=30
+            )
+            resp.raise_for_status()
+            sb_data = resp.json()
+            sandbox_id = sb_data["id"]
+
+            sandbox = PooledSandbox(id=sandbox_id, state=SandboxState.STARTING)
+            with self.lock:
+                self.all_sandboxes[sandbox_id] = sandbox
+            logger.info(f"Sandbox {sandbox_id}: STARTING")
+
+            # 2. Poll until RUNNING
+            sandbox = self._wait_until_running(sandbox, timeout=180)
+
+            # 3. Run initialization script
+            sandbox.state = SandboxState.PREPARING
+            logger.info(f"Sandbox {sandbox_id}: PREPARING (running init script)")
+            self._run_init_script(sandbox)
+
+            # 4. Mark as ready and add to queue
+            sandbox.state = SandboxState.READY
+            sandbox.ready_at = datetime.now()
+            self.ready_queue.put(sandbox)
+            logger.info(
+                f"Sandbox {sandbox_id}: READY "
+                f"(took {(sandbox.ready_at - sandbox.created_at).seconds}s)"
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to provision sandbox: {e}", exc_info=True)
+            if sandbox:
+                sandbox.state = SandboxState.FAILED
+                sandbox.error_message = str(e)
+
+    def _wait_until_running(
+        self, sandbox: PooledSandbox, timeout: int = 180
+    ) -> PooledSandbox:
+        """Poll sandbox status until it reaches RUNNING state."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            resp = requests.get(
+                f"{self.base_url}/api/v1/sandboxes",
+                headers=self.headers,
+                params={"id": sandbox.id},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            results = resp.json()
+            if not results or results[0] is None:
+                raise ValueError(f"Sandbox {sandbox.id} not found")
+
+            sb_data = results[0]
+            status = sb_data["status"]
+            sandbox.init_log.append(f"Status: {status}")
+
+            if status == "RUNNING":
+                # Extract agent-server URL and session key
+                sandbox.agent_url = self._extract_agent_url(sb_data)
+                sandbox.session_api_key = sb_data["session_api_key"]
+                return sandbox
+
+            time.sleep(3)
+
+        raise TimeoutError(
+            f"Sandbox {sandbox.id} did not reach RUNNING within {timeout}s"
+        )
+
+    def _extract_agent_url(self, sandbox_data: dict) -> str:
+        """Extract AGENT_SERVER URL from sandbox exposed_urls."""
+        url = next(
+            (
+                u["url"]
+                for u in sandbox_data.get("exposed_urls", [])
+                if u["name"] == "AGENT_SERVER"
+            ),
+            None,
+        )
+        if not url:
+            raise ValueError(
+                f"AGENT_SERVER URL not found in sandbox {sandbox_data['id']}"
+            )
+        return url
+
+    def _run_init_script(self, sandbox: PooledSandbox) -> None:
+        """Execute the initialization script in the sandbox."""
+        if not sandbox.agent_url or not sandbox.session_api_key:
+            raise ValueError(f"Sandbox {sandbox.id} missing agent URL or session key")
+
+        session_headers = {"X-Session-API-Key": sandbox.session_api_key}
+
+        # Upload the init script
+        sandbox.init_log.append("Uploading init script...")
+        upload_resp = requests.post(
+            f"{sandbox.agent_url}/api/upload-files",
+            headers=session_headers,
+            files={"file": ("init.sh", self.init_script, "text/plain")},
+            data={"destination": "/tmp/init.sh"},
+            timeout=30,
+        )
+        upload_resp.raise_for_status()
+
+        # Execute the script
+        sandbox.init_log.append("Executing init script...")
+        exec_resp = requests.post(
+            f"{sandbox.agent_url}/api/bash/execute_bash_command",
+            headers=session_headers,
+            json={
+                "command": f"chmod +x /tmp/init.sh && SANDBOX_ID={sandbox.id} bash /tmp/init.sh",
+                "timeout": 300,
+            },
+            timeout=320,
+        )
+        exec_resp.raise_for_status()
+        result = exec_resp.json()
+
+        # Log output
+        stdout = (result.get("stdout") or "").strip()
+        stderr = (result.get("stderr") or "").strip()
+        if stdout:
+            sandbox.init_log.extend(stdout.split("\n")[-20:])  # Last 20 lines
+        if stderr:
+            sandbox.init_log.append(f"[stderr]: {stderr}")
+
+        exit_code = result.get("exit_code", -1)
+        if exit_code != 0:
+            raise RuntimeError(
+                f"Init script failed with exit code {exit_code}: {stderr or stdout}"
+            )
+
+        sandbox.init_log.append("✅ Initialization complete")
+
+    def get_ready_sandbox(self) -> PooledSandbox | None:
+        """Get a ready sandbox from the pool (non-blocking)."""
+        try:
+            sandbox = self.ready_queue.get_nowait()
+            sandbox.state = SandboxState.ALLOCATED
+            sandbox.allocated_at = datetime.now()
+            return sandbox
+        except queue.Empty:
+            return None
+
+    def get_pool_status(self) -> dict:
+        """Get current pool status for the UI."""
+        with self.lock:
+            sandboxes_list = sorted(
+                [sb.to_dict() for sb in self.all_sandboxes.values()],
+                key=lambda x: x["created_at"],
+            )
+
+        return {
+            "pool_size": self.pool_size,
+            "threshold": self.threshold,
+            "ready_count": self.ready_queue.qsize(),
+            "sandboxes": sandboxes_list,
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    def attach_conversation(
+        self, sandbox: PooledSandbox, message: str
+    ) -> str:
+        """Attach a new conversation to the given sandbox."""
+        payload = {
+            "sandbox_id": sandbox.id,
+            "initial_message": {
+                "role": "user",
+                "content": [{"type": "text", "text": message}],
+            },
+            "title": f"Warm Pool Demo - {datetime.now().strftime('%H:%M:%S')}",
+        }
+
+        resp = requests.post(
+            f"{self.base_url}/api/v1/app-conversations",
+            headers=self.headers,
+            json=payload,
+            timeout=30,
+        )
+        resp.raise_for_status()
+        task = resp.json()
+
+        # Poll start task until we get conversation ID
+        task_id = task["id"]
+        conv_id = task.get("app_conversation_id")
+        timeout = 60
+        deadline = time.monotonic() + timeout
+
+        while not conv_id and time.monotonic() < deadline:
+            time.sleep(2)
+            resp = requests.get(
+                f"{self.base_url}/api/v1/app-conversations/start-tasks",
+                headers=self.headers,
+                params={"ids": task_id},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            items = resp.json()
+            item = items[0] if isinstance(items, list) else items
+            conv_id = item.get("app_conversation_id")
+
+        if not conv_id:
+            raise TimeoutError(f"Start task {task_id} did not produce conversation ID")
+
+        sandbox.conversation_id = conv_id
+        logger.info(f"Conversation {conv_id} attached to sandbox {sandbox.id}")
+        return conv_id
+
+    def shutdown(self) -> None:
+        """Graceful shutdown."""
+        self.running = False
+        logger.info("Pool controller shutting down")
+
+
+# Flask Application
+app = Flask(__name__)
+CORS(app)
+
+pool_controller: PoolController | None = None
+
+
+@app.route("/")
+def index():
+    """Serve the main UI."""
+    return render_template("index.html")
+
+
+@app.route("/api/pool/status")
+def pool_status():
+    """Get current pool status."""
+    if not pool_controller:
+        return jsonify({"error": "Pool controller not initialized"}), 500
+    return jsonify(pool_controller.get_pool_status())
+
+
+@app.route("/api/pool/events")
+def pool_events():
+    """Server-Sent Events stream for real-time pool updates."""
+
+    def generate():
+        while True:
+            if pool_controller:
+                status = pool_controller.get_pool_status()
+                yield f"data: {json.dumps(status)}\n\n"
+            time.sleep(2)
+
+    return app.response_class(generate(), mimetype="text/event-stream")
+
+
+@app.route("/api/conversation/start", methods=["POST"])
+def start_conversation():
+    """Start a new conversation with a sandbox from the pool."""
+    if not pool_controller:
+        return jsonify({"error": "Pool controller not initialized"}), 500
+
+    data = request.json or {}
+    message = data.get("message", "Hello! I'm ready to help.")
+
+    # Get a ready sandbox
+    sandbox = pool_controller.get_ready_sandbox()
+    if not sandbox:
+        return (
+            jsonify(
+                {
+                    "error": "No ready sandboxes available",
+                    "ready_count": pool_controller.ready_queue.qsize(),
+                }
+            ),
+            503,
+        )
+
+    # Attach conversation
+    try:
+        conv_id = pool_controller.attach_conversation(sandbox, message)
+        conv_url = f"{pool_controller.base_url}/conversations/{conv_id}"
+        return jsonify(
+            {
+                "conversation_id": conv_id,
+                "conversation_url": conv_url,
+                "sandbox_id": sandbox.id,
+                "message": "Conversation started with pre-warmed sandbox!",
+            }
+        )
+    except Exception as e:
+        logger.error(f"Failed to attach conversation: {e}", exc_info=True)
+        return jsonify({"error": str(e)}), 500
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="Warm Sandbox Pool Controller")
+    p.add_argument(
+        "--api-key",
+        default=os.environ.get("OH_API_KEY"),
+        help="OpenHands Cloud API key (env: OH_API_KEY)",
+    )
+    p.add_argument(
+        "--base-url",
+        default=os.environ.get("OH_API_BASE", "https://app.all-hands.dev"),
+        help="OpenHands base URL (env: OH_API_BASE)",
+    )
+    p.add_argument(
+        "--pool-size",
+        type=int,
+        default=int(os.environ.get("POOL_SIZE", "3")),
+        help="Target pool size (env: POOL_SIZE, default: 3)",
+    )
+    p.add_argument(
+        "--threshold",
+        type=int,
+        default=int(os.environ.get("POOL_THRESHOLD", "2")),
+        help="Refill when pool drops below this (env: POOL_THRESHOLD, default: 2)",
+    )
+    p.add_argument(
+        "--sandbox-spec-id",
+        default=os.environ.get("SANDBOX_SPEC_ID"),
+        help="Optional sandbox spec ID (env: SANDBOX_SPEC_ID)",
+    )
+    p.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", "5000")),
+        help="Web server port (env: PORT, default: 5000)",
+    )
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    if not args.api_key:
+        sys.exit("Error: OH_API_KEY is required. Set via --api-key or environment variable.")
+
+    # Initialize pool controller
+    global pool_controller
+    pool_controller = PoolController(
+        api_key=args.api_key,
+        base_url=args.base_url,
+        pool_size=args.pool_size,
+        threshold=args.threshold,
+        sandbox_spec_id=args.sandbox_spec_id,
+    )
+    pool_controller.start()
+
+    # Start Flask app
+    logger.info(f"Starting web server on port {args.port}")
+    logger.info(f"Open http://localhost:{args.port} in your browser")
+    app.run(host="0.0.0.0", port=args.port, debug=False, threaded=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/warm-sandbox-pool/pyproject.toml b/warm-sandbox-pool/pyproject.toml
new file mode 100644
index 0000000..efbe79e
--- /dev/null
+++ b/warm-sandbox-pool/pyproject.toml
@@ -0,0 +1,18 @@
+[project]
+name = "warm-sandbox-pool"
+version = "0.1.0"
+description = "Warm Sandbox Pool demonstration for OpenHands"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "flask>=3.0.0",
+    "flask-cors>=4.0.0",
+    "requests>=2.31.0",
+]
+
+[project.scripts]
+pool-controller = "pool_controller:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
diff --git a/warm-sandbox-pool/requirements.txt b/warm-sandbox-pool/requirements.txt
new file mode 100644
index 0000000..d3ffc4b
--- /dev/null
+++ b/warm-sandbox-pool/requirements.txt
@@ -0,0 +1,3 @@
+flask>=3.0.0
+flask-cors>=4.0.0
+requests>=2.31.0
diff --git a/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh b/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh
new file mode 100644
index 0000000..443c7b4
--- /dev/null
+++ b/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh
@@ -0,0 +1,139 @@
+#!/bin/bash
+# Sandbox initialization script for warm pool
+# This demonstrates the preparation steps needed to make a sandbox ready for use
+# In a production deployment, you would replace this with your actual application setup
+
+set -e  # Exit on error
+
+echo "🚀 Starting sandbox initialization..."
+echo "📦 Sandbox ID: ${SANDBOX_ID:-unknown}"
+
+# 1. Install Ruby (using system package manager for speed in this demo)
+echo "📥 Installing Ruby..."
+apt-get update -qq
+apt-get install -y -qq ruby-full ruby-dev build-essential > /dev/null 2>&1
+ruby --version
+
+# 2. Install Sinatra gem
+echo "💎 Installing Sinatra gem..."
+gem install sinatra --no-document > /dev/null 2>&1
+
+# 3. Create service directory
+echo "📁 Setting up service directory..."
+mkdir -p /workspace/services
+cd /workspace/services
+
+# 4. Copy the quote service (in production, this would be your actual app)
+echo "📝 Deploying quote service..."
+cat > /workspace/services/quote_service.rb << 'RUBY_SERVICE_EOF'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'sinatra'
+require 'json'
+
+set :port, 4567
+set :bind, '0.0.0.0'
+
+QUOTES = [
+  { author: 'Alan Kay', text: 'The best way to predict the future is to invent it.' },
+  { author: 'Donald Knuth', text: 'Premature optimization is the root of all evil.' },
+  { author: 'Rob Pike', text: 'Simplicity is complicated.' },
+  { author: 'Ken Thompson', text: 'When in doubt, use brute force.' },
+  { author: 'Yukihiro Matsumoto', text: 'Ruby is designed to make programmers happy.' },
+  { author: 'David Heinemeier Hansson', text: 'Convention over configuration.' },
+  { author: 'Sandi Metz', text: 'Duplication is far cheaper than the wrong abstraction.' },
+  { author: 'Martin Fowler', text: 'Any fool can write code that a computer can understand. Good programmers write code that humans can understand.' }
+].freeze
+
+get '/health' do
+  content_type :json
+  { status: 'ok', service: 'quote_service', version: '1.0.0' }.to_json
+end
+
+get '/quote' do
+  content_type :json
+  quote = QUOTES.sample
+  { quote: quote[:text], author: quote[:author], timestamp: Time.now.iso8601 }.to_json
+end
+
+get '/quotes' do
+  content_type :json
+  { quotes: QUOTES, count: QUOTES.size }.to_json
+end
+
+get '/quotes/:author' do
+  content_type :json
+  author_param = params['author'].downcase
+  matches = QUOTES.select { |q| q[:author].downcase.include?(author_param) }
+  if matches.empty?
+    status 404
+    { error: 'No quotes found for that author' }.to_json
+  else
+    { quotes: matches, count: matches.size }.to_json
+  end
+end
+
+get '/' do
+  content_type :json
+  {
+    service: 'Quote of the Day API',
+    version: '1.0.0',
+    endpoints: { health: 'GET /health', random_quote: 'GET /quote', all_quotes: 'GET /quotes', by_author: 'GET /quotes/:author' },
+    sandbox_id: ENV['SANDBOX_ID'] || 'unknown',
+    message: 'This service demonstrates a pre-initialized Ruby application in a warm sandbox. In production, this would be your actual application service.'
+  }.to_json
+end
+RUBY_SERVICE_EOF
+
+chmod +x /workspace/services/quote_service.rb
+
+# 5. Start the service in background
+echo "🌐 Starting quote service on port 4567..."
+cd /workspace/services
+nohup ruby quote_service.rb > /tmp/quote_service.log 2>&1 &
+SERVICE_PID=$!
+echo "Service PID: $SERVICE_PID"
+
+# 6. Wait for service to be ready (with timeout)
+echo "⏳ Waiting for service to respond..."
+TIMEOUT=30
+ELAPSED=0
+while [ $ELAPSED -lt $TIMEOUT ]; do
+    if curl -sf http://localhost:4567/health > /dev/null 2>&1; then
+        echo "✅ Service is healthy!"
+        curl -s http://localhost:4567/health | jq . || true
+        break
+    fi
+    sleep 1
+    ELAPSED=$((ELAPSED + 1))
+done
+
+if [ $ELAPSED -ge $TIMEOUT ]; then
+    echo "❌ Service failed to start within ${TIMEOUT}s"
+    echo "Service log:"
+    cat /tmp/quote_service.log
+    exit 1
+fi
+
+# 7. Final verification - test the main endpoint
+echo "🧪 Testing service endpoint..."
+QUOTE_RESPONSE=$(curl -s http://localhost:4567/quote)
+echo "Sample quote: $QUOTE_RESPONSE"
+
+# 8. Create a marker file to indicate successful initialization
+echo "✅ Creating ready marker..."
+echo "$(date -Iseconds)" > /workspace/.sandbox_ready
+echo "SANDBOX_ID=${SANDBOX_ID:-unknown}" >> /workspace/.sandbox_ready
+echo "SERVICE_PID=$SERVICE_PID" >> /workspace/.sandbox_ready
+echo "RUBY_VERSION=$(ruby --version)" >> /workspace/.sandbox_ready
+
+echo ""
+echo "🎉 Sandbox initialization complete!"
+echo "📊 Summary:"
+echo "   - Ruby: $(ruby --version | cut -d' ' -f2)"
+echo "   - Sinatra: installed"
+echo "   - Quote Service: running on port 4567 (PID $SERVICE_PID)"
+echo "   - Status: READY"
+echo ""
+echo "💡 In production, replace this initialization with your application-specific setup"
diff --git a/warm-sandbox-pool/sandbox_prep/quote_service.rb b/warm-sandbox-pool/sandbox_prep/quote_service.rb
new file mode 100644
index 0000000..436deee
--- /dev/null
+++ b/warm-sandbox-pool/sandbox_prep/quote_service.rb
@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo Ruby/Sinatra service for warm sandbox pool example
+# A simple "quote of the day" API that runs in each initialized sandbox
+
+require 'sinatra'
+require 'json'
+
+set :port, 4567
+set :bind, '0.0.0.0'
+
+QUOTES = [
+  { author: 'Alan Kay', text: 'The best way to predict the future is to invent it.' },
+  { author: 'Donald Knuth', text: 'Premature optimization is the root of all evil.' },
+  { author: 'Rob Pike', text: 'Simplicity is complicated.' },
+  { author: 'Ken Thompson', text: 'When in doubt, use brute force.' },
+  { author: 'Yukihiro Matsumoto', text: 'Ruby is designed to make programmers happy.' },
+  { author: 'David Heinemeier Hansson', text: 'Convention over configuration.' },
+  { author: 'Sandi Metz', text: 'Duplication is far cheaper than the wrong abstraction.' },
+  { author: 'Martin Fowler', text: 'Any fool can write code that a computer can understand. Good programmers write code that humans can understand.' }
+].freeze
+
+# Health check endpoint
+get '/health' do
+  content_type :json
+  { status: 'ok', service: 'quote_service', version: '1.0.0' }.to_json
+end
+
+# Get a random quote
+get '/quote' do
+  content_type :json
+  quote = QUOTES.sample
+  {
+    quote: quote[:text],
+    author: quote[:author],
+    timestamp: Time.now.iso8601
+  }.to_json
+end
+
+# Get all quotes
+get '/quotes' do
+  content_type :json
+  { quotes: QUOTES, count: QUOTES.size }.to_json
+end
+
+# Get quote by author (case-insensitive partial match)
+get '/quotes/:author' do
+  content_type :json
+  author_param = params['author'].downcase
+  matches = QUOTES.select { |q| q[:author].downcase.include?(author_param) }
+  
+  if matches.empty?
+    status 404
+    { error: 'No quotes found for that author' }.to_json
+  else
+    { quotes: matches, count: matches.size }.to_json
+  end
+end
+
+# Info endpoint
+get '/' do
+  content_type :json
+  {
+    service: 'Quote of the Day API',
+    version: '1.0.0',
+    endpoints: {
+      health: 'GET /health',
+      random_quote: 'GET /quote',
+      all_quotes: 'GET /quotes',
+      by_author: 'GET /quotes/:author'
+    },
+    sandbox_id: ENV['SANDBOX_ID'] || 'unknown'
+  }.to_json
+end
+
+# Startup message
+puts "🚀 Quote Service starting on port #{settings.port}"
+puts "📚 Loaded #{QUOTES.size} quotes"
+puts "🎯 Sandbox ID: #{ENV['SANDBOX_ID'] || 'not set'}"
diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
new file mode 100644
index 0000000..34a6948
--- /dev/null
+++ b/warm-sandbox-pool/static/app.js
@@ -0,0 +1,253 @@
+// Warm Sandbox Pool - Frontend JavaScript
+
+class PoolUI {
+    constructor() {
+        this.poolReady = false;
+        this.eventSource = null;
+        this.initialize();
+    }
+
+    initialize() {
+        this.setupEventStream();
+        this.setupConversationForm();
+    }
+
+    setupEventStream() {
+        // Connect to Server-Sent Events for real-time pool updates
+        this.eventSource = new EventSource('/api/pool/events');
+        
+        this.eventSource.onmessage = (event) => {
+            const data = JSON.parse(event.data);
+            this.updateUI(data);
+        };
+
+        this.eventSource.onerror = (error) => {
+            console.error('EventSource error:', error);
+            // Try to reconnect after 5 seconds
+            setTimeout(() => {
+                if (this.eventSource.readyState === EventSource.CLOSED) {
+                    this.setupEventStream();
+                }
+            }, 5000);
+        };
+    }
+
+    updateUI(poolStatus) {
+        // Update pool stats
+        document.getElementById('pool-size').textContent = poolStatus.pool_size;
+        document.getElementById('ready-count').textContent = poolStatus.ready_count;
+        document.getElementById('threshold').textContent = poolStatus.threshold;
+
+        // Update sandbox list
+        this.renderSandboxes(poolStatus.sandboxes);
+
+        // Check if pool is ready
+        const wasReady = this.poolReady;
+        this.poolReady = poolStatus.ready_count > 0;
+
+        // Toggle conversation interface visibility
+        if (this.poolReady && !wasReady) {
+            this.showConversationInterface();
+        } else if (!this.poolReady && wasReady) {
+            this.hideConversationInterface();
+        }
+    }
+
+    renderSandboxes(sandboxes) {
+        const container = document.getElementById('sandbox-list');
+        
+        if (sandboxes.length === 0) {
+            container.innerHTML = '<p style="text-align: center; color: #6b7280;">No sandboxes yet...</p>';
+            return;
+        }
+
+        container.innerHTML = sandboxes.map(sb => this.renderSandboxCard(sb)).join('');
+    }
+
+    renderSandboxCard(sandbox) {
+        const statusClass = `status-${sandbox.state.toLowerCase()}`;
+        const statusEmoji = this.getStatusEmoji(sandbox.state);
+        
+        const duration = this.calculateDuration(sandbox.created_at, sandbox.ready_at);
+        const logs = sandbox.init_log && sandbox.init_log.length > 0 
+            ? this.renderLogs(sandbox.init_log)
+            : '';
+
+        const conversationLink = sandbox.conversation_id
+            ? `<a href="/conversations/${sandbox.conversation_id}" target="_blank" class="conversation-link">
+                   🔗 View Conversation
+               </a>`
+            : '';
+
+        const errorMessage = sandbox.error_message
+            ? `<div class="error-message">❌ ${this.escapeHtml(sandbox.error_message)}</div>`
+            : '';
+
+        return `
+            <div class="sandbox-card">
+                <div class="sandbox-header">
+                    <span class="status-badge ${statusClass}">${statusEmoji} ${sandbox.state}</span>
+                    <span class="sandbox-id">${this.shortId(sandbox.id)}</span>
+                </div>
+                ${duration ? `<div class="sandbox-details">⏱️ ${duration}</div>` : ''}
+                ${logs}
+                ${conversationLink}
+                ${errorMessage}
+            </div>
+        `;
+    }
+
+    getStatusEmoji(state) {
+        const emojis = {
+            'STARTING': '🔴',
+            'PREPARING': '🟡',
+            'READY': '🟢',
+            'ALLOCATED': '🟦',
+            'FAILED': '⚠️'
+        };
+        return emojis[state] || '⚪';
+    }
+
+    renderLogs(logs) {
+        const recentLogs = logs.slice(-5); // Last 5 lines
+        return `
+            <div class="sandbox-log">
+                ${recentLogs.map(line => 
+                    `<div class="sandbox-log-line">${this.escapeHtml(line)}</div>`
+                ).join('')}
+            </div>
+        `;
+    }
+
+    calculateDuration(createdAt, readyAt) {
+        if (!readyAt) return null;
+        
+        const created = new Date(createdAt);
+        const ready = new Date(readyAt);
+        const seconds = Math.floor((ready - created) / 1000);
+        
+        return `Ready in ${seconds}s`;
+    }
+
+    shortId(id) {
+        return id.length > 12 ? `${id.substring(0, 8)}...${id.substring(id.length - 4)}` : id;
+    }
+
+    escapeHtml(text) {
+        const div = document.createElement('div');
+        div.textContent = text;
+        return div.innerHTML;
+    }
+
+    showConversationInterface() {
+        document.getElementById('waiting-state').style.display = 'none';
+        document.getElementById('ready-state').style.display = 'block';
+    }
+
+    hideConversationInterface() {
+        document.getElementById('waiting-state').style.display = 'block';
+        document.getElementById('ready-state').style.display = 'none';
+    }
+
+    setupConversationForm() {
+        const form = document.getElementById('message-input');
+        const button = document.getElementById('start-btn');
+        const resultArea = document.getElementById('result-area');
+
+        // Set default message
+        form.value = "Check if the quote service is running on localhost:4567 and fetch me a random quote. Show me the result.";
+
+        button.addEventListener('click', async () => {
+            const message = form.value.trim();
+            
+            if (!message) {
+                alert('Please enter a message');
+                return;
+            }
+
+            if (!this.poolReady) {
+                alert('Pool is not ready yet. Please wait for at least one sandbox to be ready.');
+                return;
+            }
+
+            // Disable button during request
+            button.disabled = true;
+            button.textContent = '⏳ Starting...';
+
+            try {
+                const response = await fetch('/api/conversation/start', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify({ message })
+                });
+
+                const data = await response.json();
+
+                if (!response.ok) {
+                    throw new Error(data.error || 'Failed to start conversation');
+                }
+
+                // Show success result
+                this.showResult(data, false);
+                
+                // Clear input
+                form.value = '';
+
+            } catch (error) {
+                console.error('Error starting conversation:', error);
+                this.showResult({ error: error.message }, true);
+            } finally {
+                button.disabled = false;
+                button.textContent = '🚀 Start Conversation';
+            }
+        });
+    }
+
+    showResult(data, isError) {
+        const resultArea = document.getElementById('result-area');
+        
+        if (isError) {
+            resultArea.className = 'result-area error';
+            resultArea.innerHTML = `
+                <h3>❌ Error</h3>
+                <p>${this.escapeHtml(data.error)}</p>
+            `;
+        } else {
+            resultArea.className = 'result-area';
+            resultArea.innerHTML = `
+                <h3>✅ ${this.escapeHtml(data.message)}</h3>
+                <p><strong>Sandbox ID:</strong> <code>${this.escapeHtml(data.sandbox_id)}</code></p>
+                <p><strong>Conversation ID:</strong> <code>${this.escapeHtml(data.conversation_id)}</code></p>
+                <a href="${this.escapeHtml(data.conversation_url)}" target="_blank">
+                    🔗 Open Conversation in OpenHands
+                </a>
+                <p style="margin-top: 16px; font-size: 0.875rem; color: #6b7280;">
+                    The pool will automatically provision a new sandbox to refill the allocated slot.
+                </p>
+            `;
+        }
+
+        resultArea.style.display = 'block';
+
+        // Scroll to result
+        resultArea.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+    }
+
+    cleanup() {
+        if (this.eventSource) {
+            this.eventSource.close();
+        }
+    }
+}
+
+// Initialize when DOM is ready
+document.addEventListener('DOMContentLoaded', () => {
+    const poolUI = new PoolUI();
+
+    // Cleanup on page unload
+    window.addEventListener('beforeunload', () => {
+        poolUI.cleanup();
+    });
+});
diff --git a/warm-sandbox-pool/static/styles.css b/warm-sandbox-pool/static/styles.css
new file mode 100644
index 0000000..79914f0
--- /dev/null
+++ b/warm-sandbox-pool/static/styles.css
@@ -0,0 +1,458 @@
+/* Warm Sandbox Pool - UI Styles */
+
+:root {
+    --primary-color: #2563eb;
+    --success-color: #10b981;
+    --warning-color: #f59e0b;
+    --danger-color: #ef4444;
+    --info-color: #3b82f6;
+    --bg-light: #f9fafb;
+    --bg-white: #ffffff;
+    --text-primary: #111827;
+    --text-secondary: #6b7280;
+    --border-color: #e5e7eb;
+    --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+}
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif;
+    background-color: var(--bg-light);
+    color: var(--text-primary);
+    line-height: 1.6;
+}
+
+.container {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 20px;
+}
+
+header {
+    text-align: center;
+    margin-bottom: 30px;
+    padding: 20px;
+    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+    color: white;
+    border-radius: 12px;
+    box-shadow: var(--shadow-lg);
+}
+
+header h1 {
+    font-size: 2.5rem;
+    margin-bottom: 8px;
+}
+
+header .subtitle {
+    font-size: 1.1rem;
+    opacity: 0.95;
+}
+
+.main-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    margin-bottom: 20px;
+}
+
+@media (max-width: 1024px) {
+    .main-grid {
+        grid-template-columns: 1fr;
+    }
+}
+
+.panel {
+    background: var(--bg-white);
+    border-radius: 12px;
+    padding: 24px;
+    box-shadow: var(--shadow);
+}
+
+.panel h2 {
+    font-size: 1.5rem;
+    margin-bottom: 16px;
+    color: var(--text-primary);
+}
+
+/* Pool Panel */
+.pool-stats {
+    display: flex;
+    gap: 16px;
+    margin-bottom: 20px;
+    padding: 16px;
+    background: var(--bg-light);
+    border-radius: 8px;
+}
+
+.stat {
+    flex: 1;
+    text-align: center;
+}
+
+.stat-label {
+    display: block;
+    font-size: 0.875rem;
+    color: var(--text-secondary);
+    margin-bottom: 4px;
+}
+
+.stat-value {
+    display: block;
+    font-size: 1.5rem;
+    font-weight: bold;
+    color: var(--text-primary);
+}
+
+.stat-value.ready-count {
+    color: var(--success-color);
+}
+
+/* Sandbox List */
+.sandbox-list {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    margin-bottom: 20px;
+    max-height: 500px;
+    overflow-y: auto;
+}
+
+.sandbox-card {
+    padding: 16px;
+    border: 2px solid var(--border-color);
+    border-radius: 8px;
+    background: var(--bg-white);
+    transition: all 0.2s;
+}
+
+.sandbox-card:hover {
+    border-color: var(--primary-color);
+    box-shadow: var(--shadow);
+}
+
+.sandbox-header {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 8px;
+}
+
+.sandbox-id {
+    font-family: 'Courier New', monospace;
+    font-size: 0.875rem;
+    color: var(--text-secondary);
+    flex: 1;
+}
+
+.status-badge {
+    padding: 4px 12px;
+    border-radius: 12px;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+}
+
+.status-starting {
+    background: #fee2e2;
+    color: #991b1b;
+}
+
+.status-preparing {
+    background: #fef3c7;
+    color: #92400e;
+}
+
+.status-ready {
+    background: #d1fae5;
+    color: #065f46;
+}
+
+.status-allocated {
+    background: #dbeafe;
+    color: #1e40af;
+}
+
+.status-failed {
+    background: #fecaca;
+    color: #7f1d1d;
+}
+
+.sandbox-details {
+    font-size: 0.875rem;
+    color: var(--text-secondary);
+    margin-top: 8px;
+}
+
+.sandbox-log {
+    margin-top: 8px;
+    padding: 8px;
+    background: #f9fafb;
+    border-left: 3px solid var(--info-color);
+    border-radius: 4px;
+    font-family: 'Courier New', monospace;
+    font-size: 0.75rem;
+    max-height: 100px;
+    overflow-y: auto;
+}
+
+.sandbox-log-line {
+    margin: 2px 0;
+}
+
+.conversation-link {
+    display: inline-block;
+    margin-top: 8px;
+    color: var(--primary-color);
+    text-decoration: none;
+    font-weight: 500;
+}
+
+.conversation-link:hover {
+    text-decoration: underline;
+}
+
+/* Pool Legend */
+.pool-legend {
+    padding: 16px;
+    background: var(--bg-light);
+    border-radius: 8px;
+}
+
+.pool-legend h3 {
+    font-size: 1rem;
+    margin-bottom: 12px;
+}
+
+.legend-item {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin: 8px 0;
+    font-size: 0.875rem;
+}
+
+/* Conversation Panel */
+.waiting-state {
+    text-align: center;
+    padding: 60px 20px;
+}
+
+.spinner {
+    border: 4px solid var(--border-color);
+    border-top: 4px solid var(--primary-color);
+    border-radius: 50%;
+    width: 50px;
+    height: 50px;
+    animation: spin 1s linear infinite;
+    margin: 0 auto 20px;
+}
+
+@keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+
+.waiting-state p {
+    font-size: 1.1rem;
+    color: var(--text-secondary);
+    margin: 8px 0;
+}
+
+.waiting-subtext {
+    font-size: 0.875rem !important;
+    font-style: italic;
+}
+
+.ready-state {
+    animation: fadeIn 0.5s;
+}
+
+@keyframes fadeIn {
+    from { opacity: 0; transform: translateY(10px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.info-box {
+    padding: 16px;
+    background: #dbeafe;
+    border-left: 4px solid var(--info-color);
+    border-radius: 8px;
+    margin-bottom: 20px;
+}
+
+.info-box p {
+    margin: 4px 0;
+}
+
+.conversation-form {
+    margin-bottom: 20px;
+}
+
+.conversation-form label {
+    display: block;
+    font-weight: 500;
+    margin-bottom: 8px;
+}
+
+.conversation-form textarea {
+    width: 100%;
+    padding: 12px;
+    border: 2px solid var(--border-color);
+    border-radius: 8px;
+    font-family: inherit;
+    font-size: 1rem;
+    resize: vertical;
+    transition: border-color 0.2s;
+}
+
+.conversation-form textarea:focus {
+    outline: none;
+    border-color: var(--primary-color);
+}
+
+.btn-primary {
+    width: 100%;
+    padding: 14px 24px;
+    background: var(--primary-color);
+    color: white;
+    border: none;
+    border-radius: 8px;
+    font-size: 1rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all 0.2s;
+    margin-top: 12px;
+}
+
+.btn-primary:hover {
+    background: #1d4ed8;
+    transform: translateY(-2px);
+    box-shadow: var(--shadow-lg);
+}
+
+.btn-primary:active {
+    transform: translateY(0);
+}
+
+.btn-primary:disabled {
+    background: var(--text-secondary);
+    cursor: not-allowed;
+    transform: none;
+}
+
+.result-area {
+    margin-top: 20px;
+    padding: 16px;
+    background: #d1fae5;
+    border-left: 4px solid var(--success-color);
+    border-radius: 8px;
+    animation: fadeIn 0.5s;
+}
+
+.result-area.error {
+    background: #fee2e2;
+    border-left-color: var(--danger-color);
+}
+
+.result-area h3 {
+    margin-bottom: 12px;
+}
+
+.result-area p {
+    margin: 8px 0;
+}
+
+.result-area a {
+    display: inline-block;
+    margin-top: 12px;
+    padding: 10px 20px;
+    background: white;
+    color: var(--primary-color);
+    text-decoration: none;
+    border-radius: 6px;
+    font-weight: 600;
+    transition: all 0.2s;
+}
+
+.result-area a:hover {
+    background: var(--primary-color);
+    color: white;
+    transform: translateY(-2px);
+}
+
+/* Info Section */
+.info-section {
+    margin-top: 30px;
+    padding-top: 20px;
+    border-top: 2px solid var(--border-color);
+}
+
+.info-section h3 {
+    font-size: 1.25rem;
+    margin: 20px 0 10px;
+}
+
+.info-section h4 {
+    font-size: 1rem;
+    margin: 16px 0 8px;
+    color: var(--text-secondary);
+}
+
+.info-section ul {
+    margin-left: 20px;
+    margin-bottom: 12px;
+}
+
+.info-section li {
+    margin: 6px 0;
+    color: var(--text-secondary);
+}
+
+.info-section code {
+    background: var(--bg-light);
+    padding: 2px 6px;
+    border-radius: 4px;
+    font-family: 'Courier New', monospace;
+    font-size: 0.875rem;
+}
+
+.note {
+    margin-top: 16px;
+    padding: 12px;
+    background: #fef3c7;
+    border-left: 4px solid var(--warning-color);
+    border-radius: 8px;
+    font-size: 0.875rem;
+}
+
+/* Footer */
+footer {
+    text-align: center;
+    padding: 20px;
+    color: var(--text-secondary);
+    font-size: 0.875rem;
+}
+
+footer a {
+    color: var(--primary-color);
+    text-decoration: none;
+}
+
+footer a:hover {
+    text-decoration: underline;
+}
+
+/* Error State */
+.error-message {
+    color: var(--danger-color);
+    background: #fee2e2;
+    padding: 12px;
+    border-radius: 8px;
+    margin-top: 12px;
+}
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
new file mode 100644
index 0000000..86ad915
--- /dev/null
+++ b/warm-sandbox-pool/templates/index.html
@@ -0,0 +1,135 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Warm Sandbox Pool Demo</title>
+    <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>🔥 Warm Sandbox Pool</h1>
+            <p class="subtitle">Pre-initialized OpenHands sandboxes with Ruby services ready to go</p>
+        </header>
+
+        <div class="main-grid">
+            <!-- Left Panel: Pool Visualization -->
+            <div class="panel pool-panel">
+                <h2>📦 Sandbox Pool</h2>
+                <div class="pool-stats" id="pool-stats">
+                    <div class="stat">
+                        <span class="stat-label">Target Size:</span>
+                        <span class="stat-value" id="pool-size">-</span>
+                    </div>
+                    <div class="stat">
+                        <span class="stat-label">Ready:</span>
+                        <span class="stat-value ready-count" id="ready-count">0</span>
+                    </div>
+                    <div class="stat">
+                        <span class="stat-label">Threshold:</span>
+                        <span class="stat-value" id="threshold">-</span>
+                    </div>
+                </div>
+
+                <div id="sandbox-list" class="sandbox-list">
+                    <!-- Sandbox cards will be inserted here -->
+                </div>
+
+                <div class="pool-legend">
+                    <h3>Status Legend</h3>
+                    <div class="legend-item">
+                        <span class="status-badge status-starting">🔴</span>
+                        <span>STARTING - Provisioning sandbox</span>
+                    </div>
+                    <div class="legend-item">
+                        <span class="status-badge status-preparing">🟡</span>
+                        <span>PREPARING - Installing Ruby & gems</span>
+                    </div>
+                    <div class="legend-item">
+                        <span class="status-badge status-ready">🟢</span>
+                        <span>READY - Available for conversations</span>
+                    </div>
+                    <div class="legend-item">
+                        <span class="status-badge status-allocated">🟦</span>
+                        <span>ALLOCATED - In use by conversation</span>
+                    </div>
+                    <div class="legend-item">
+                        <span class="status-badge status-failed">⚠️</span>
+                        <span>FAILED - Initialization error</span>
+                    </div>
+                </div>
+            </div>
+
+            <!-- Right Panel: Conversation Interface -->
+            <div class="panel conversation-panel">
+                <h2>💬 Start a Conversation</h2>
+                
+                <div id="waiting-state" class="waiting-state">
+                    <div class="spinner"></div>
+                    <p>Preparing sandbox pool...</p>
+                    <p class="waiting-subtext">This takes about 30-60 seconds on first start</p>
+                </div>
+
+                <div id="ready-state" class="ready-state" style="display: none;">
+                    <div class="info-box">
+                        <p><strong>✨ Pool is ready!</strong></p>
+                        <p>Type a message below to start an OpenHands conversation. A pre-warmed sandbox with Ruby and Sinatra already installed will be allocated instantly.</p>
+                    </div>
+
+                    <div class="conversation-form">
+                        <label for="message-input">Your message to the agent:</label>
+                        <textarea 
+                            id="message-input" 
+                            rows="4" 
+                            placeholder="Example: Check if the quote service is running on localhost:4567 and fetch me a random quote."
+                        ></textarea>
+                        
+                        <button id="start-btn" class="btn-primary">
+                            🚀 Start Conversation
+                        </button>
+                    </div>
+
+                    <div id="result-area" class="result-area" style="display: none;">
+                        <!-- Conversation results will appear here -->
+                    </div>
+                </div>
+
+                <div class="info-section">
+                    <h3>About This Demo</h3>
+                    <p>This demonstrates the <strong>Warm Sandbox Pool</strong> technique for eliminating initialization delays when using OpenHands agents.</p>
+                    
+                    <h4>What's Pre-Installed:</h4>
+                    <ul>
+                        <li>Ruby 3.x runtime</li>
+                        <li>Sinatra gem</li>
+                        <li>Quote service API running on port 4567</li>
+                    </ul>
+
+                    <h4>Try These Commands:</h4>
+                    <ul>
+                        <li>"Check if the quote service is running on localhost:4567"</li>
+                        <li>"Fetch a random quote from localhost:4567/quote and show it to me"</li>
+                        <li>"List all quotes available in the service"</li>
+                        <li>"Show me the Ruby version installed in this sandbox"</li>
+                    </ul>
+
+                    <div class="note">
+                        <strong>💡 For Custom Applications:</strong> Replace the demo Sinatra service in <code>sandbox_prep/init_ruby_service.sh</code> with your actual application initialization commands.
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <footer>
+        <p>
+            <strong>Warm Sandbox Pool</strong> - 
+            Alternative to custom images for deploying Ruby-based services |
+            <a href="https://github.com/jpshackelford/oh-examples" target="_blank">View on GitHub</a>
+        </p>
+    </footer>
+
+    <script src="{{ url_for('static', filename='app.js') }}"></script>
+</body>
+</html>
diff --git a/warm-sandbox-pool/test_structure.py b/warm-sandbox-pool/test_structure.py
new file mode 100644
index 0000000..dafacce
--- /dev/null
+++ b/warm-sandbox-pool/test_structure.py
@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+Simple test to verify the warm-sandbox-pool structure is complete.
+Run this before deploying to catch any missing files.
+"""
+
+from pathlib import Path
+
+def check_structure():
+    """Verify all expected files exist."""
+    base = Path(__file__).parent
+    
+    required_files = [
+        "README.md",
+        "QUICKSTART.md", 
+        "pool_controller.py",
+        "requirements.txt",
+        "pyproject.toml",
+        "sandbox_prep/init_ruby_service.sh",
+        "sandbox_prep/quote_service.rb",
+        "static/app.js",
+        "static/styles.css",
+        "templates/index.html",
+    ]
+    
+    missing = []
+    for file_path in required_files:
+        full_path = base / file_path
+        if not full_path.exists():
+            missing.append(file_path)
+    
+    if missing:
+        print("❌ Missing files:")
+        for f in missing:
+            print(f"   - {f}")
+        return False
+    
+    print("✅ All required files present")
+    
+    # Check that scripts are executable
+    scripts = [
+        base / "pool_controller.py",
+        base / "sandbox_prep" / "init_ruby_service.sh",
+    ]
+    
+    non_executable = []
+    for script in scripts:
+        if not script.stat().st_mode & 0o111:  # Check execute bit
+            non_executable.append(script.name)
+    
+    if non_executable:
+        print("⚠️  Scripts missing execute permission:")
+        for s in non_executable:
+            print(f"   - {s}")
+        print("   Run: chmod +x pool_controller.py sandbox_prep/*.sh")
+    else:
+        print("✅ All scripts are executable")
+    
+    # Check README has warm sandbox pool context
+    readme = (base / "README.md").read_text()
+    if "Warm Sandbox Pool" in readme:
+        print("✅ README mentions Warm Sandbox Pool")
+    else:
+        print("⚠️  README doesn't mention Warm Sandbox Pool")
+    
+    # Check init script has proper shebang
+    init_script = (base / "sandbox_prep" / "init_ruby_service.sh").read_text()
+    if init_script.startswith("#!/bin/bash"):
+        print("✅ Init script has proper shebang")
+    else:
+        print("⚠️  Init script missing #!/bin/bash shebang")
+    
+    print("\n📊 Structure check complete!")
+    return len(missing) == 0
+
+
+if __name__ == "__main__":
+    import sys
+    success = check_structure()
+    sys.exit(0 if success else 1)

From 3cfa1907ed4e7e7d7818b1bd7d1b26050b801c1a Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sat, 3 Oct 2026 16:50:23 +0000
Subject: [PATCH 2/9] Point references at OpenHands/enterprise-cookbook

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md        | 4 ++--
 warm-sandbox-pool/templates/index.html | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index 1cc45c6..1418d62 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -12,8 +12,8 @@ Get the Warm Sandbox Pool demo running in 5 minutes.
 
 ```bash
 # Clone the repository
-git clone https://github.com/jpshackelford/oh-examples.git
-cd oh-examples/warm-sandbox-pool
+git clone https://github.com/OpenHands/enterprise-cookbook.git
+cd enterprise-cookbook/warm-sandbox-pool
 
 # Install Python dependencies (use uv or pip)
 pip install -r requirements.txt
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index 86ad915..d89aecc 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -126,7 +126,7 @@ <h4>Try These Commands:</h4>
         <p>
             <strong>Warm Sandbox Pool</strong> - 
             Alternative to custom images for deploying Ruby-based services |
-            <a href="https://github.com/jpshackelford/oh-examples" target="_blank">View on GitHub</a>
+            <a href="https://github.com/OpenHands/enterprise-cookbook" target="_blank">View on GitHub</a>
         </p>
     </footer>
 

From 24f7efb8bbbeb7eaa10b780023ecf0c9042d2b94 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sat, 3 Oct 2026 17:04:02 +0000
Subject: [PATCH 3/9] Fix pre-commit failures (formatting, whitespace, line
 length)

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md               | 10 +++----
 warm-sandbox-pool/README.md                   |  2 +-
 warm-sandbox-pool/pool_controller.py          | 30 +++++++++++++------
 .../sandbox_prep/quote_service.rb             |  2 +-
 warm-sandbox-pool/static/app.js               | 20 ++++++-------
 warm-sandbox-pool/templates/index.html        | 14 ++++-----
 warm-sandbox-pool/test_structure.py           | 24 ++++++++-------
 7 files changed, 58 insertions(+), 44 deletions(-)

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index 1418d62..f81b4ac 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -215,11 +215,11 @@ warm-sandbox-pool/
 
 You've successfully run the demo when:
 
-✅ Pool shows 3 sandboxes in READY state  
-✅ You can start a conversation and get instant allocation  
-✅ The conversation link opens in OpenHands  
-✅ The agent can interact with the pre-installed quote service  
-✅ Pool automatically provisions a replacement sandbox  
+✅ Pool shows 3 sandboxes in READY state\
+✅ You can start a conversation and get instant allocation\
+✅ The conversation link opens in OpenHands\
+✅ The agent can interact with the pre-installed quote service\
+✅ Pool automatically provisions a replacement sandbox
 
 **Total time from zero to working demo: ~5 minutes**
 
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
index a638f5f..8dec1c9 100644
--- a/warm-sandbox-pool/README.md
+++ b/warm-sandbox-pool/README.md
@@ -6,7 +6,7 @@ Demonstrates maintaining a pool of pre-initialized "warm" sandboxes that late-bi
 
 ## Context: Alternative to Custom Images
 
-When applications have components that run outside the agent control loop and must be available on the system where the agent is running, a custom image is not the only mechanism for packaging these dependencies. 
+When applications have components that run outside the agent control loop and must be available on the system where the agent is running, a custom image is not the only mechanism for packaging these dependencies.
 
 Even when using custom images in OpenHands Enterprise, some scenarios require additional tasks to be completed on the running sandbox to make it ready for use. **If these tasks take more than a few seconds, the Warm Sandbox Pool technique eliminates the apparent delay an end-user would see** by preparing a pool of pre-initialized sandboxes that late-bind to conversations when an end-user begins to interact with the agent.
 
diff --git a/warm-sandbox-pool/pool_controller.py b/warm-sandbox-pool/pool_controller.py
index 725d1aa..5283ac8 100644
--- a/warm-sandbox-pool/pool_controller.py
+++ b/warm-sandbox-pool/pool_controller.py
@@ -25,12 +25,12 @@
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any
 
 import requests
 from flask import Flask, jsonify, render_template, request
 from flask_cors import CORS
 
+
 # Configure logging
 logging.basicConfig(
     level=logging.INFO,
@@ -72,7 +72,9 @@ def to_dict(self) -> dict:
             "agent_url": self.agent_url,
             "created_at": self.created_at.isoformat(),
             "ready_at": self.ready_at.isoformat() if self.ready_at else None,
-            "allocated_at": self.allocated_at.isoformat() if self.allocated_at else None,
+            "allocated_at": self.allocated_at.isoformat()
+            if self.allocated_at
+            else None,
             "conversation_id": self.conversation_id,
             "error_message": self.error_message,
             "init_log": self.init_log[-10:],  # Last 10 log lines
@@ -163,9 +165,16 @@ def _provision_and_init_sandbox(self) -> None:
         try:
             # 1. Create sandbox via Cloud API
             logger.info("Creating new sandbox...")
-            params = {"sandbox_spec_id": self.sandbox_spec_id} if self.sandbox_spec_id else None
+            params = (
+                {"sandbox_spec_id": self.sandbox_spec_id}
+                if self.sandbox_spec_id
+                else None
+            )
             resp = requests.post(
-                f"{self.base_url}/api/v1/sandboxes", headers=self.headers, params=params, timeout=30
+                f"{self.base_url}/api/v1/sandboxes",
+                headers=self.headers,
+                params=params,
+                timeout=30,
             )
             resp.raise_for_status()
             sb_data = resp.json()
@@ -272,7 +281,10 @@ def _run_init_script(self, sandbox: PooledSandbox) -> None:
             f"{sandbox.agent_url}/api/bash/execute_bash_command",
             headers=session_headers,
             json={
-                "command": f"chmod +x /tmp/init.sh && SANDBOX_ID={sandbox.id} bash /tmp/init.sh",
+                "command": (
+                    "chmod +x /tmp/init.sh && "
+                    f"SANDBOX_ID={sandbox.id} bash /tmp/init.sh"
+                ),
                 "timeout": 300,
             },
             timeout=320,
@@ -322,9 +334,7 @@ def get_pool_status(self) -> dict:
             "timestamp": datetime.now().isoformat(),
         }
 
-    def attach_conversation(
-        self, sandbox: PooledSandbox, message: str
-    ) -> str:
+    def attach_conversation(self, sandbox: PooledSandbox, message: str) -> str:
         """Attach a new conversation to the given sandbox."""
         payload = {
             "sandbox_id": sandbox.id,
@@ -492,7 +502,9 @@ def main():
     args = parse_args()
 
     if not args.api_key:
-        sys.exit("Error: OH_API_KEY is required. Set via --api-key or environment variable.")
+        sys.exit(
+            "Error: OH_API_KEY is required. Set via --api-key or environment variable."
+        )
 
     # Initialize pool controller
     global pool_controller
diff --git a/warm-sandbox-pool/sandbox_prep/quote_service.rb b/warm-sandbox-pool/sandbox_prep/quote_service.rb
index 436deee..9f648eb 100644
--- a/warm-sandbox-pool/sandbox_prep/quote_service.rb
+++ b/warm-sandbox-pool/sandbox_prep/quote_service.rb
@@ -49,7 +49,7 @@
   content_type :json
   author_param = params['author'].downcase
   matches = QUOTES.select { |q| q[:author].downcase.include?(author_param) }
-  
+
   if matches.empty?
     status 404
     { error: 'No quotes found for that author' }.to_json
diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
index 34a6948..3fecc93 100644
--- a/warm-sandbox-pool/static/app.js
+++ b/warm-sandbox-pool/static/app.js
@@ -15,7 +15,7 @@ class PoolUI {
     setupEventStream() {
         // Connect to Server-Sent Events for real-time pool updates
         this.eventSource = new EventSource('/api/pool/events');
-        
+
         this.eventSource.onmessage = (event) => {
             const data = JSON.parse(event.data);
             this.updateUI(data);
@@ -55,7 +55,7 @@ class PoolUI {
 
     renderSandboxes(sandboxes) {
         const container = document.getElementById('sandbox-list');
-        
+
         if (sandboxes.length === 0) {
             container.innerHTML = '<p style="text-align: center; color: #6b7280;">No sandboxes yet...</p>';
             return;
@@ -67,9 +67,9 @@ class PoolUI {
     renderSandboxCard(sandbox) {
         const statusClass = `status-${sandbox.state.toLowerCase()}`;
         const statusEmoji = this.getStatusEmoji(sandbox.state);
-        
+
         const duration = this.calculateDuration(sandbox.created_at, sandbox.ready_at);
-        const logs = sandbox.init_log && sandbox.init_log.length > 0 
+        const logs = sandbox.init_log && sandbox.init_log.length > 0
             ? this.renderLogs(sandbox.init_log)
             : '';
 
@@ -112,7 +112,7 @@ class PoolUI {
         const recentLogs = logs.slice(-5); // Last 5 lines
         return `
             <div class="sandbox-log">
-                ${recentLogs.map(line => 
+                ${recentLogs.map(line =>
                     `<div class="sandbox-log-line">${this.escapeHtml(line)}</div>`
                 ).join('')}
             </div>
@@ -121,11 +121,11 @@ class PoolUI {
 
     calculateDuration(createdAt, readyAt) {
         if (!readyAt) return null;
-        
+
         const created = new Date(createdAt);
         const ready = new Date(readyAt);
         const seconds = Math.floor((ready - created) / 1000);
-        
+
         return `Ready in ${seconds}s`;
     }
 
@@ -159,7 +159,7 @@ class PoolUI {
 
         button.addEventListener('click', async () => {
             const message = form.value.trim();
-            
+
             if (!message) {
                 alert('Please enter a message');
                 return;
@@ -191,7 +191,7 @@ class PoolUI {
 
                 // Show success result
                 this.showResult(data, false);
-                
+
                 // Clear input
                 form.value = '';
 
@@ -207,7 +207,7 @@ class PoolUI {
 
     showResult(data, isError) {
         const resultArea = document.getElementById('result-area');
-        
+
         if (isError) {
             resultArea.className = 'result-area error';
             resultArea.innerHTML = `
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index d89aecc..ec3465d 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -64,7 +64,7 @@ <h3>Status Legend</h3>
             <!-- Right Panel: Conversation Interface -->
             <div class="panel conversation-panel">
                 <h2>💬 Start a Conversation</h2>
-                
+
                 <div id="waiting-state" class="waiting-state">
                     <div class="spinner"></div>
                     <p>Preparing sandbox pool...</p>
@@ -79,12 +79,12 @@ <h2>💬 Start a Conversation</h2>
 
                     <div class="conversation-form">
                         <label for="message-input">Your message to the agent:</label>
-                        <textarea 
-                            id="message-input" 
-                            rows="4" 
+                        <textarea
+                            id="message-input"
+                            rows="4"
                             placeholder="Example: Check if the quote service is running on localhost:4567 and fetch me a random quote."
                         ></textarea>
-                        
+
                         <button id="start-btn" class="btn-primary">
                             🚀 Start Conversation
                         </button>
@@ -98,7 +98,7 @@ <h2>💬 Start a Conversation</h2>
                 <div class="info-section">
                     <h3>About This Demo</h3>
                     <p>This demonstrates the <strong>Warm Sandbox Pool</strong> technique for eliminating initialization delays when using OpenHands agents.</p>
-                    
+
                     <h4>What's Pre-Installed:</h4>
                     <ul>
                         <li>Ruby 3.x runtime</li>
@@ -124,7 +124,7 @@ <h4>Try These Commands:</h4>
 
     <footer>
         <p>
-            <strong>Warm Sandbox Pool</strong> - 
+            <strong>Warm Sandbox Pool</strong> -
             Alternative to custom images for deploying Ruby-based services |
             <a href="https://github.com/OpenHands/enterprise-cookbook" target="_blank">View on GitHub</a>
         </p>
diff --git a/warm-sandbox-pool/test_structure.py b/warm-sandbox-pool/test_structure.py
index dafacce..3059308 100644
--- a/warm-sandbox-pool/test_structure.py
+++ b/warm-sandbox-pool/test_structure.py
@@ -6,13 +6,14 @@
 
 from pathlib import Path
 
+
 def check_structure():
     """Verify all expected files exist."""
     base = Path(__file__).parent
-    
+
     required_files = [
         "README.md",
-        "QUICKSTART.md", 
+        "QUICKSTART.md",
         "pool_controller.py",
         "requirements.txt",
         "pyproject.toml",
@@ -22,32 +23,32 @@ def check_structure():
         "static/styles.css",
         "templates/index.html",
     ]
-    
+
     missing = []
     for file_path in required_files:
         full_path = base / file_path
         if not full_path.exists():
             missing.append(file_path)
-    
+
     if missing:
         print("❌ Missing files:")
         for f in missing:
             print(f"   - {f}")
         return False
-    
+
     print("✅ All required files present")
-    
+
     # Check that scripts are executable
     scripts = [
         base / "pool_controller.py",
         base / "sandbox_prep" / "init_ruby_service.sh",
     ]
-    
+
     non_executable = []
     for script in scripts:
         if not script.stat().st_mode & 0o111:  # Check execute bit
             non_executable.append(script.name)
-    
+
     if non_executable:
         print("⚠️  Scripts missing execute permission:")
         for s in non_executable:
@@ -55,26 +56,27 @@ def check_structure():
         print("   Run: chmod +x pool_controller.py sandbox_prep/*.sh")
     else:
         print("✅ All scripts are executable")
-    
+
     # Check README has warm sandbox pool context
     readme = (base / "README.md").read_text()
     if "Warm Sandbox Pool" in readme:
         print("✅ README mentions Warm Sandbox Pool")
     else:
         print("⚠️  README doesn't mention Warm Sandbox Pool")
-    
+
     # Check init script has proper shebang
     init_script = (base / "sandbox_prep" / "init_ruby_service.sh").read_text()
     if init_script.startswith("#!/bin/bash"):
         print("✅ Init script has proper shebang")
     else:
         print("⚠️  Init script missing #!/bin/bash shebang")
-    
+
     print("\n📊 Structure check complete!")
     return len(missing) == 0
 
 
 if __name__ == "__main__":
     import sys
+
     success = check_structure()
     sys.exit(0 if success else 1)

From 12e86755f71e0589941db5a23ebffad55e23d910 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 7 Oct 2026 19:08:24 +0000
Subject: [PATCH 4/9] warm-sandbox-pool: make the recipe work and stop leaking
 sandboxes

Found by running the recipe end to end against a live OpenHands instance.

Broken as written:
- Init script upload used a non-existent agent-server endpoint
  (/api/upload-files); use /api/file/upload?path=...
- Init script ran apt-get/gem as the non-root sandbox user; use sudo
- Current Sinatra needs rackup and puma to boot

Resource safety:
- Delete a sandbox as soon as provisioning fails
- Stop refilling after MAX_FAILURES consecutive failures (was unbounded)
- Delete unused pool sandboxes on shutdown (SIGTERM/Ctrl-C)
- Bind the UI to 127.0.0.1 by default and drop the open CORS config

Other fixes:
- Upload quote_service.rb instead of a divergent copy embedded in the script
- UI conversation link pointed at localhost instead of OpenHands
- Add INIT_TIMEOUT, MAX_FAILURES, HOST settings that the docs described
- README/QUICKSTART: correct Ruby install method, service access, timings,
  troubleshooting commands and parameter docs
- test_structure.py also syntax-checks the init script and controller

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md               |  36 ++--
 warm-sandbox-pool/README.md                   | 104 ++++++++----
 warm-sandbox-pool/pool_controller.py          | 155 ++++++++++++++----
 warm-sandbox-pool/pyproject.toml              |   1 -
 warm-sandbox-pool/requirements.txt            |   1 -
 .../sandbox_prep/init_ruby_service.sh         |  91 +++-------
 .../sandbox_prep/quote_service.rb             |   1 +
 warm-sandbox-pool/static/app.js               |   7 +-
 warm-sandbox-pool/templates/index.html        |   6 +-
 warm-sandbox-pool/test_structure.py           |  22 ++-
 10 files changed, 264 insertions(+), 160 deletions(-)
 mode change 100644 => 100755 warm-sandbox-pool/pool_controller.py
 mode change 100644 => 100755 warm-sandbox-pool/sandbox_prep/init_ruby_service.sh

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index f81b4ac..15f2e04 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -8,7 +8,7 @@ Get the Warm Sandbox Pool demo running in 5 minutes.
 - **Python 3.10+** - Check with `python --version`
 - **Git** - To clone this repository
 
-## Installation (30 seconds)
+## Installation (about a minute)
 
 ```bash
 # Clone the repository
@@ -22,13 +22,18 @@ pip install -r requirements.txt
 uv pip install -e .
 ```
 
-## Run the Demo (10 seconds)
+## Run the Demo
+
+> **This creates real sandboxes.** The controller starts `POOL_SIZE` (default 3)
+> sandboxes right away and keeps refilling the pool. For a first try use
+> `POOL_SIZE=1 POOL_THRESHOLD=1`. Press Ctrl-C to stop: unused pool sandboxes are
+> deleted, sandboxes already attached to a conversation are left running.
 
 ```bash
 # Set your API key
 export OH_API_KEY=your_api_key_here
 
-# Start the pool controller
+# Start the pool controller (add OH_API_BASE=... for a non-default instance)
 python pool_controller.py
 
 # You should see:
@@ -44,7 +49,7 @@ python pool_controller.py
 
 2. **Watch the pool initialize**:
    - You'll see "Preparing pool..." message
-   - 3 sandboxes will start initializing (takes ~30-60 seconds each)
+   - 3 sandboxes will start initializing (roughly 10-30 seconds each)
    - Watch them progress: 🔴 STARTING → 🟡 PREPARING → 🟢 READY
 
 3. **Start a conversation**:
@@ -57,7 +62,8 @@ python pool_controller.py
 
 4. **Observe the magic**:
    - A ready sandbox is instantly pulled from the pool
-   - OpenHands conversation starts immediately (no wait!)
+   - The conversation attaches to it after a few seconds, with no sandbox boot or
+     Ruby install wait
    - Click the conversation link to see your agent working
    - Watch the pool automatically provision a new sandbox to refill
 
@@ -69,8 +75,8 @@ User clicks "Start" → Wait 30-60s for sandbox → Agent starts
                        ⏳ User sees delay
 
 With Warm Pool:
-User clicks "Start" → Instant sandbox → Agent starts
-                       ⚡ No apparent delay
+User clicks "Start" → Warm sandbox → Agent starts
+                       ⚡ No sandbox boot or install delay
                        (Pool refills in background)
 ```
 
@@ -117,6 +123,7 @@ Customize via environment variables:
 export OH_API_KEY=your_key
 export OH_API_BASE=https://app.all-hands.dev  # or your instance
 export PORT=5000                               # Web UI port
+export HOST=127.0.0.1                          # UI has no auth; keep it local
 
 # Pool sizing
 export POOL_SIZE=3          # How many ready sandboxes to maintain
@@ -124,20 +131,23 @@ export POOL_THRESHOLD=2     # Start refilling when ready count drops below this
 
 # Sandbox config (optional)
 export SANDBOX_SPEC_ID=your_spec_id  # Use custom runtime image
+export INIT_TIMEOUT=300              # Seconds the init script may run
+export MAX_FAILURES=3                # Stop refilling after N failures in a row
 ```
 
 ## Troubleshooting
 
 ### "No ready sandboxes available" error
-- **Wait longer**: Initial pool fill takes 1-3 minutes
+- **Wait longer**: Initial pool fill usually takes under a minute, more if the
+  platform is busy
 - **Check API key**: Make sure `OH_API_KEY` is valid
 - **View logs**: Look at terminal output for error messages
 - **Check web UI**: Look for FAILED sandboxes and error messages
 
 ### Sandboxes stuck in PREPARING
 - **Check init script**: May be timing out or failing
-- **Increase timeout**: Set higher init timeout in code
-- **Test manually**: Use `start-sandbox/` example to debug
+- **Increase timeout**: Set `INIT_TIMEOUT` higher
+- **Test manually**: See "Sandboxes Get Stuck in PREPARING" in `README.md`
 
 ### "OH_API_KEY is required" error
 ```bash
@@ -195,9 +205,10 @@ warm-sandbox-pool/
 ├── pool_controller.py             🎛️  Main backend (Flask + pool logic)
 ├── requirements.txt               📦 Python dependencies
 ├── pyproject.toml                 📦 UV-compatible project config
+├── test_structure.py              ✅ Sanity check of the example's files
 ├── sandbox_prep/
 │   ├── init_ruby_service.sh      🔧 Demo: Ruby/Sinatra init
-│   └── quote_service.rb          💎 Demo Ruby service
+│   └── quote_service.rb          💎 Demo Ruby service (uploaded to each sandbox)
 ├── static/
 │   ├── app.js                    🎨 Frontend JavaScript
 │   └── styles.css                🎨 UI styling
@@ -208,7 +219,6 @@ warm-sandbox-pool/
 ## Getting Help
 
 - **Documentation**: Read `README.md` for full details
-- **Example Code**: All files are heavily commented
 - **Related Examples**: Check `../start-sandbox/` and `../clone-and-attach/`
 
 ## Success Criteria
@@ -221,6 +231,6 @@ You've successfully run the demo when:
 ✅ The agent can interact with the pre-installed quote service\
 ✅ Pool automatically provisions a replacement sandbox
 
-**Total time from zero to working demo: ~5 minutes**
+**Total time from zero to working demo: a few minutes**
 
 Now you understand how warm sandbox pools work and can adapt this technique for your own application deployment!
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
index 8dec1c9..aa7df8b 100644
--- a/warm-sandbox-pool/README.md
+++ b/warm-sandbox-pool/README.md
@@ -92,9 +92,18 @@ python pool_controller.py
 
 Then open http://localhost:5000 in your browser.
 
+> **Heads up: this creates real sandboxes.** The controller immediately starts
+> `POOL_SIZE` sandboxes (default 3) and keeps topping the pool up as you use them.
+> Try it with `POOL_SIZE=1 POOL_THRESHOLD=1` first. Press Ctrl-C (or send SIGTERM)
+> to stop: every sandbox still sitting in the pool is deleted. Sandboxes already
+> attached to a conversation are left running, like any other conversation sandbox.
+> If the controller is killed with SIGKILL it cannot clean up, so check your sandbox
+> list afterwards.
+
 ### What You'll See
 
-1. **Initial State**: "Preparing pool..." message while 3 sandboxes initialize
+1. **Initial State**: "Preparing pool..." message while the sandboxes initialize
+   (roughly 10-30 seconds each when the platform has capacity, longer otherwise)
 2. **Pool Visualization**: Real-time status of each sandbox:
    - 🔴 **STARTING**: OpenHands is provisioning the sandbox
    - 🟡 **PREPARING**: Installing Ruby, gems, starting service
@@ -108,21 +117,26 @@ Then open http://localhost:5000 in your browser.
 Environment variables:
 
 - `OH_API_KEY`: OpenHands Cloud API key (required)
-- `OH_API_BASE`: API base URL (default: `https://app.all-hands.dev`)
+- `OH_API_BASE`: API base URL (default: `https://app.all-hands.dev`). Set this to
+  point at a different OpenHands instance.
 - `POOL_SIZE`: Target pool size (default: `3`)
 - `POOL_THRESHOLD`: Trigger refill when pool drops below this (default: `2`)
+- `SANDBOX_SPEC_ID`: Optional sandbox spec (runtime image) to use for pool sandboxes
+- `INIT_TIMEOUT`: Seconds the init script may run in a sandbox (default: `300`)
+- `MAX_FAILURES`: Stop refilling after this many provisioning failures in a row
+  (default: `3`). A failed sandbox is deleted immediately, so a broken init script
+  cannot silently create sandboxes forever.
+- `HOST`: Address the web UI binds to (default: `127.0.0.1`). The UI has no
+  authentication and can start conversations with your API key, so only widen this
+  on a trusted network.
 - `PORT`: Web server port (default: `5000`)
 
 ### Testing the Ruby Service
 
-Once a sandbox is in READY state, the Sinatra service is running on port 4567. You can test it:
-
-```bash
-# Get the sandbox ID from the web UI, then:
-curl https://work-1-<sandbox-slug>.prod-runtime.all-hands.dev:12000/quote
-```
+Once a sandbox is in READY state, the Sinatra service is listening on port 4567
+**inside** the sandbox. That port is not exposed publicly, so reach it from the
+sandbox itself. The easiest way is to start a conversation and ask the agent:
 
-Or ask the agent to interact with it:
 ```
 "Call the quote service running on localhost:4567 and show me today's quote"
 ```
@@ -131,12 +145,15 @@ Or ask the agent to interact with it:
 
 ### Sandbox Initialization Process
 
-Each sandbox goes through these preparation steps (see `sandbox_prep/init_ruby_service.sh`):
+The controller uploads `sandbox_prep/init_ruby_service.sh` and
+`sandbox_prep/quote_service.rb` to the sandbox's agent-server (`POST /api/file/upload`)
+and runs the script (`POST /api/bash/execute_bash_command`). The script does the
+following (sandboxes run as a non-root user, so it uses `sudo` for installs):
 
-1. **Install Ruby**: Uses rbenv to install Ruby 3.2
-2. **Install Sinatra**: Gem install sinatra
-3. **Deploy Service**: Copies the quote service code
-4. **Start Service**: Launches the Sinatra app in the background
+1. **Install Ruby**: `apt-get install ruby-full` (Ruby 3.3 on current sandbox images)
+2. **Install Sinatra**: `gem install sinatra rackup puma`
+3. **Deploy Service**: Copies the uploaded `quote_service.rb` into `/workspace/services`
+4. **Start Service**: Launches the Sinatra app in the background on port 4567
 5. **Verify**: Confirms the service responds to health checks
 
 This simulates a realistic scenario where your agent needs specific tools/services pre-installed.
@@ -149,7 +166,10 @@ The `PoolController` class handles:
 - **Monitoring**: Polls sandbox status until RUNNING
 - **Initialization**: Executes preparation scripts via agent-server API
 - **Queue Management**: Thread-safe queue of ready sandboxes
-- **Auto-Refill**: Background thread maintains pool size
+- **Auto-Refill**: Background thread maintains pool size, and stops after
+  `MAX_FAILURES` consecutive failures
+- **Cleanup**: Deletes failed sandboxes immediately and all unused pool sandboxes
+  on shutdown
 - **Conversation Binding**: Attaches conversations to pre-warmed sandboxes
 
 ### Real-Time Updates
@@ -161,11 +181,14 @@ The web UI uses Server-Sent Events (SSE) to stream pool state updates in real-ti
 ```
 warm-sandbox-pool/
 ├── README.md                          # This file
+├── QUICKSTART.md                      # Short run-it-now guide
 ├── pool_controller.py                 # Flask backend + pool manager
 ├── requirements.txt                   # Python dependencies
+├── pyproject.toml                     # Same dependencies, for uv
+├── test_structure.py                  # Sanity check of the example's files
 ├── sandbox_prep/
 │   ├── init_ruby_service.sh          # Bash script to initialize each sandbox
-│   └── quote_service.rb              # Ruby/Sinatra demo service
+│   └── quote_service.rb              # Ruby/Sinatra demo service (uploaded to each sandbox)
 ├── static/
 │   ├── app.js                        # Frontend JavaScript
 │   └── styles.css                    # UI styling
@@ -180,10 +203,9 @@ warm-sandbox-pool/
 Pre-install language runtimes (Ruby, Java, Go) that take time to set up:
 
 ```bash
-# In init script
-rbenv install 3.2.0
-rbenv global 3.2.0
-gem install rails bundler
+# In init script (sandboxes run as a non-root user; use sudo for system installs)
+sudo apt-get install -y ruby-full
+sudo gem install rails bundler
 ```
 
 ### 2. Service Dependencies
@@ -217,11 +239,10 @@ Replace the demo Sinatra service with your actual application initialization:
 ```bash
 # In init script (replace sandbox_prep/init_ruby_service.sh contents)
 # Install Ruby (or use a runtime that already has it)
-rbenv install 3.2.0
-rbenv global 3.2.0
+sudo apt-get install -y ruby-full
 
 # Install your application gems
-gem install your_gem_name
+sudo gem install your_gem_name
 
 # Initialize your application
 cd /workspace
@@ -264,8 +285,8 @@ Edit `sandbox_prep/init_ruby_service.sh` to install additional tools:
 
 ```bash
 # Install Node.js
-curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
-apt-get install -y nodejs
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
 
 # Install Python packages
 pip install pandas numpy jupyter
@@ -277,11 +298,9 @@ Replace `sandbox_prep/quote_service.rb` with your own Ruby application or gem.
 
 ### Adjust Pool Parameters
 
-```python
-# In pool_controller.py
-POOL_SIZE = 5              # Maintain 5 ready sandboxes
-POOL_THRESHOLD = 3         # Refill when below 3
-INIT_TIMEOUT = 600         # Allow 10 minutes for initialization
+```bash
+POOL_SIZE=5 POOL_THRESHOLD=3 INIT_TIMEOUT=600 python pool_controller.py
+# Maintain 5 ready sandboxes, refill when below 3, allow 10 minutes for init
 ```
 
 ### Add Health Checks
@@ -300,22 +319,35 @@ done
 
 ### Pool Never Reaches Ready State
 
-Check the initialization logs in the web UI. Common issues:
+Check the controller's terminal output and the init log in the web UI. After
+`MAX_FAILURES` failures in a row the controller stops creating sandboxes and the UI
+says so. Common issues:
 - Ruby installation timeout (increase `INIT_TIMEOUT`)
 - Network issues downloading gems
 - Insufficient sandbox resources
 
 ### Sandboxes Get Stuck in PREPARING
 
-Look at the agent-server command output. The init script may be failing. Test it manually:
+Failed sandboxes are deleted right away, so to debug the init script keep a
+sandbox alive and run it by hand. Create one with the `start-sandbox/` example (or
+`POST /api/v1/sandboxes`), then read its `session_api_key` and `AGENT_SERVER` URL
+from `GET /api/v1/sandboxes?id=<sandbox-id>`:
 
 ```bash
-# Get a sandbox URL from the UI, then:
-curl -X POST https://<agent-server-url>/api/bash/execute_bash_command \
-  -H "X-Session-API-Key: <session-key>" \
-  -d '{"command": "bash /workspace/init_ruby_service.sh", "timeout": 300}'
+AGENT=https://<agent-server-url>
+KEY=<session-api-key>
+
+curl -X POST "$AGENT/api/file/upload?path=/tmp/init.sh" \
+  -H "X-Session-API-Key: $KEY" -F file=@sandbox_prep/init_ruby_service.sh
+curl -X POST "$AGENT/api/file/upload?path=/tmp/quote_service.rb" \
+  -H "X-Session-API-Key: $KEY" -F file=@sandbox_prep/quote_service.rb
+curl -X POST "$AGENT/api/bash/execute_bash_command" \
+  -H "X-Session-API-Key: $KEY" -H "Content-Type: application/json" \
+  -d '{"command": "bash /tmp/init.sh", "timeout": 300}'
 ```
 
+Delete the sandbox when you are done (`DELETE /api/v1/sandboxes/<id>?sandbox_id=<id>`).
+
 ### High Resource Usage
 
 Reduce `POOL_SIZE` or implement smarter pool management:
diff --git a/warm-sandbox-pool/pool_controller.py b/warm-sandbox-pool/pool_controller.py
old mode 100644
new mode 100755
index 5283ac8..de9f0e0
--- a/warm-sandbox-pool/pool_controller.py
+++ b/warm-sandbox-pool/pool_controller.py
@@ -11,6 +11,9 @@
     python pool_controller.py
 
 Then open http://localhost:5000 in your browser.
+
+On exit (Ctrl-C / SIGTERM) every sandbox that is still in the pool is deleted.
+Sandboxes already handed to a conversation are left alone.
 """
 
 import argparse
@@ -18,6 +21,7 @@
 import logging
 import os
 import queue
+import signal
 import sys
 import threading
 import time
@@ -28,7 +32,6 @@
 
 import requests
 from flask import Flask, jsonify, render_template, request
-from flask_cors import CORS
 
 
 # Configure logging
@@ -91,32 +94,42 @@ def __init__(
         pool_size: int = 3,
         threshold: int = 2,
         sandbox_spec_id: str | None = None,
+        init_timeout: int = 300,
+        max_failures: int = 3,
     ):
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")
         self.pool_size = pool_size
         self.threshold = threshold
         self.sandbox_spec_id = sandbox_spec_id
+        self.init_timeout = init_timeout
+        self.max_failures = max_failures
 
         self.headers = {"X-Session-API-Key": api_key}
         self.ready_queue: queue.Queue[PooledSandbox] = queue.Queue()
         self.all_sandboxes: dict[str, PooledSandbox] = {}
         self.lock = threading.RLock()
         self.running = True
+        self.consecutive_failures = 0
 
-        # Load initialization script
-        self.init_script = self._load_init_script()
+        prep_dir = Path(__file__).parent / "sandbox_prep"
+        self.init_script = self._load_file(prep_dir / "init_ruby_service.sh")
+        self.service_source = self._load_file(prep_dir / "quote_service.rb")
 
         logger.info(
             f"Pool controller initialized: size={pool_size}, threshold={threshold}"
         )
 
-    def _load_init_script(self) -> str:
-        """Load the sandbox initialization script."""
-        script_path = Path(__file__).parent / "sandbox_prep" / "init_ruby_service.sh"
-        if not script_path.exists():
-            raise FileNotFoundError(f"Init script not found: {script_path}")
-        return script_path.read_text()
+    @staticmethod
+    def _load_file(path: Path) -> str:
+        if not path.exists():
+            raise FileNotFoundError(f"Sandbox prep file not found: {path}")
+        return path.read_text()
+
+    @property
+    def halted(self) -> bool:
+        """True once provisioning has failed too many times in a row."""
+        return self.consecutive_failures >= self.max_failures
 
     def start(self) -> None:
         """Start the pool management background thread."""
@@ -134,6 +147,8 @@ def _pool_manager_loop(self) -> None:
         # Maintenance loop
         while self.running:
             time.sleep(5)
+            if self.halted:
+                continue
             ready_count = self.ready_queue.qsize()
             if ready_count < self.threshold:
                 needed = self.pool_size - self._total_initializing_count() - ready_count
@@ -194,9 +209,16 @@ def _provision_and_init_sandbox(self) -> None:
             self._run_init_script(sandbox)
 
             # 4. Mark as ready and add to queue
-            sandbox.state = SandboxState.READY
-            sandbox.ready_at = datetime.now()
-            self.ready_queue.put(sandbox)
+            with self.lock:
+                accepted = self.running
+                if accepted:
+                    sandbox.state = SandboxState.READY
+                    sandbox.ready_at = datetime.now()
+                    self.ready_queue.put(sandbox)
+                    self.consecutive_failures = 0
+            if not accepted:
+                self._delete_sandbox(sandbox_id)
+                return
             logger.info(
                 f"Sandbox {sandbox_id}: READY "
                 f"(took {(sandbox.ready_at - sandbox.created_at).seconds}s)"
@@ -204,9 +226,31 @@ def _provision_and_init_sandbox(self) -> None:
 
         except Exception as e:
             logger.error(f"Failed to provision sandbox: {e}", exc_info=True)
+            with self.lock:
+                self.consecutive_failures += 1
             if sandbox:
                 sandbox.state = SandboxState.FAILED
                 sandbox.error_message = str(e)
+                self._delete_sandbox(sandbox.id)
+            if self.halted:
+                logger.error(
+                    f"{self.consecutive_failures} provisioning failures in a row: "
+                    "refilling is halted. Fix the cause and restart the controller."
+                )
+
+    def _delete_sandbox(self, sandbox_id: str) -> None:
+        """Best-effort delete so failed or unused sandboxes don't leak."""
+        try:
+            resp = requests.delete(
+                f"{self.base_url}/api/v1/sandboxes/{sandbox_id}",
+                headers=self.headers,
+                params={"sandbox_id": sandbox_id},
+                timeout=30,
+            )
+            resp.raise_for_status()
+            logger.info(f"Sandbox {sandbox_id}: deleted")
+        except Exception as e:
+            logger.warning(f"Could not delete sandbox {sandbox_id}: {e}")
 
     def _wait_until_running(
         self, sandbox: PooledSandbox, timeout: int = 180
@@ -264,30 +308,29 @@ def _run_init_script(self, sandbox: PooledSandbox) -> None:
 
         session_headers = {"X-Session-API-Key": sandbox.session_api_key}
 
-        # Upload the init script
-        sandbox.init_log.append("Uploading init script...")
-        upload_resp = requests.post(
-            f"{sandbox.agent_url}/api/upload-files",
-            headers=session_headers,
-            files={"file": ("init.sh", self.init_script, "text/plain")},
-            data={"destination": "/tmp/init.sh"},
-            timeout=30,
-        )
-        upload_resp.raise_for_status()
+        sandbox.init_log.append("Uploading init script and service...")
+        for name, content in (
+            ("init.sh", self.init_script),
+            ("quote_service.rb", self.service_source),
+        ):
+            upload_resp = requests.post(
+                f"{sandbox.agent_url}/api/file/upload",
+                headers=session_headers,
+                params={"path": f"/tmp/{name}"},
+                files={"file": (name, content, "text/plain")},
+                timeout=30,
+            )
+            upload_resp.raise_for_status()
 
-        # Execute the script
         sandbox.init_log.append("Executing init script...")
         exec_resp = requests.post(
             f"{sandbox.agent_url}/api/bash/execute_bash_command",
             headers=session_headers,
             json={
-                "command": (
-                    "chmod +x /tmp/init.sh && "
-                    f"SANDBOX_ID={sandbox.id} bash /tmp/init.sh"
-                ),
-                "timeout": 300,
+                "command": f"SANDBOX_ID={sandbox.id} bash /tmp/init.sh",
+                "timeout": self.init_timeout,
             },
-            timeout=320,
+            timeout=self.init_timeout + 20,
         )
         exec_resp.raise_for_status()
         result = exec_resp.json()
@@ -325,11 +368,17 @@ def get_pool_status(self) -> dict:
                 [sb.to_dict() for sb in self.all_sandboxes.values()],
                 key=lambda x: x["created_at"],
             )
+        for sb in sandboxes_list:
+            if sb["conversation_id"]:
+                sb["conversation_url"] = (
+                    f"{self.base_url}/conversations/{sb['conversation_id']}"
+                )
 
         return {
             "pool_size": self.pool_size,
             "threshold": self.threshold,
             "ready_count": self.ready_queue.qsize(),
+            "halted": self.halted,
             "sandboxes": sandboxes_list,
             "timestamp": datetime.now().isoformat(),
         }
@@ -381,14 +430,23 @@ def attach_conversation(self, sandbox: PooledSandbox, message: str) -> str:
         return conv_id
 
     def shutdown(self) -> None:
-        """Graceful shutdown."""
-        self.running = False
-        logger.info("Pool controller shutting down")
+        """Stop refilling and delete every sandbox not handed to a conversation."""
+        with self.lock:
+            self.running = False
+            leftovers = [
+                sb.id
+                for sb in self.all_sandboxes.values()
+                if sb.state not in (SandboxState.ALLOCATED, SandboxState.FAILED)
+            ]
+        logger.info(
+            f"Pool controller shutting down, deleting {len(leftovers)} sandbox(es)"
+        )
+        for sandbox_id in leftovers:
+            self._delete_sandbox(sandbox_id)
 
 
 # Flask Application
 app = Flask(__name__)
-CORS(app)
 
 pool_controller: PoolController | None = None
 
@@ -495,6 +553,25 @@ def parse_args():
         default=int(os.environ.get("PORT", "5000")),
         help="Web server port (env: PORT, default: 5000)",
     )
+    p.add_argument(
+        "--host",
+        default=os.environ.get("HOST", "127.0.0.1"),
+        help="Web server bind address (env: HOST, default: 127.0.0.1). "
+        "The UI has no authentication; only widen this on a trusted network.",
+    )
+    p.add_argument(
+        "--init-timeout",
+        type=int,
+        default=int(os.environ.get("INIT_TIMEOUT", "300")),
+        help="Seconds the init script may run (env: INIT_TIMEOUT, default: 300)",
+    )
+    p.add_argument(
+        "--max-failures",
+        type=int,
+        default=int(os.environ.get("MAX_FAILURES", "3")),
+        help="Stop refilling after this many consecutive provisioning failures "
+        "(env: MAX_FAILURES, default: 3)",
+    )
     return p.parse_args()
 
 
@@ -514,13 +591,19 @@ def main():
         pool_size=args.pool_size,
         threshold=args.threshold,
         sandbox_spec_id=args.sandbox_spec_id,
+        init_timeout=args.init_timeout,
+        max_failures=args.max_failures,
     )
     pool_controller.start()
 
-    # Start Flask app
-    logger.info(f"Starting web server on port {args.port}")
+    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
+
+    logger.info(f"Starting web server on {args.host}:{args.port}")
     logger.info(f"Open http://localhost:{args.port} in your browser")
-    app.run(host="0.0.0.0", port=args.port, debug=False, threaded=True)
+    try:
+        app.run(host=args.host, port=args.port, debug=False, threaded=True)
+    finally:
+        pool_controller.shutdown()
 
 
 if __name__ == "__main__":
diff --git a/warm-sandbox-pool/pyproject.toml b/warm-sandbox-pool/pyproject.toml
index efbe79e..a82676e 100644
--- a/warm-sandbox-pool/pyproject.toml
+++ b/warm-sandbox-pool/pyproject.toml
@@ -6,7 +6,6 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "flask>=3.0.0",
-    "flask-cors>=4.0.0",
     "requests>=2.31.0",
 ]
 
diff --git a/warm-sandbox-pool/requirements.txt b/warm-sandbox-pool/requirements.txt
index d3ffc4b..eab2b35 100644
--- a/warm-sandbox-pool/requirements.txt
+++ b/warm-sandbox-pool/requirements.txt
@@ -1,3 +1,2 @@
 flask>=3.0.0
-flask-cors>=4.0.0
 requests>=2.31.0
diff --git a/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh b/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh
old mode 100644
new mode 100755
index 443c7b4..4abd8c0
--- a/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh
+++ b/warm-sandbox-pool/sandbox_prep/init_ruby_service.sh
@@ -8,85 +8,38 @@ set -e  # Exit on error
 echo "🚀 Starting sandbox initialization..."
 echo "📦 Sandbox ID: ${SANDBOX_ID:-unknown}"
 
-# 1. Install Ruby (using system package manager for speed in this demo)
+# Sandboxes run as a non-root user with passwordless sudo
+SUDO=""
+if [ "$(id -u)" -ne 0 ]; then
+    SUDO="sudo -n"
+fi
+
+# Run a quiet install step; print its log only if it fails
+quiet() {
+    if ! "$@" > /tmp/init_step.log 2>&1; then
+        echo "❌ Failed: $*"
+        tail -n 20 /tmp/init_step.log
+        exit 1
+    fi
+}
+
+# 1. Install Ruby (Debian package, much faster than building with rbenv)
 echo "📥 Installing Ruby..."
-apt-get update -qq
-apt-get install -y -qq ruby-full ruby-dev build-essential > /dev/null 2>&1
+quiet $SUDO apt-get update -qq
+quiet $SUDO apt-get install -y -qq ruby-full ruby-dev build-essential
 ruby --version
 
-# 2. Install Sinatra gem
+# 2. Install Sinatra (4.x needs rackup and puma to boot)
 echo "💎 Installing Sinatra gem..."
-gem install sinatra --no-document > /dev/null 2>&1
+quiet $SUDO gem install sinatra rackup puma --no-document
 
 # 3. Create service directory
 echo "📁 Setting up service directory..."
 mkdir -p /workspace/services
-cd /workspace/services
 
-# 4. Copy the quote service (in production, this would be your actual app)
+# 4. Deploy the quote service (uploaded next to this script by the controller)
 echo "📝 Deploying quote service..."
-cat > /workspace/services/quote_service.rb << 'RUBY_SERVICE_EOF'
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'sinatra'
-require 'json'
-
-set :port, 4567
-set :bind, '0.0.0.0'
-
-QUOTES = [
-  { author: 'Alan Kay', text: 'The best way to predict the future is to invent it.' },
-  { author: 'Donald Knuth', text: 'Premature optimization is the root of all evil.' },
-  { author: 'Rob Pike', text: 'Simplicity is complicated.' },
-  { author: 'Ken Thompson', text: 'When in doubt, use brute force.' },
-  { author: 'Yukihiro Matsumoto', text: 'Ruby is designed to make programmers happy.' },
-  { author: 'David Heinemeier Hansson', text: 'Convention over configuration.' },
-  { author: 'Sandi Metz', text: 'Duplication is far cheaper than the wrong abstraction.' },
-  { author: 'Martin Fowler', text: 'Any fool can write code that a computer can understand. Good programmers write code that humans can understand.' }
-].freeze
-
-get '/health' do
-  content_type :json
-  { status: 'ok', service: 'quote_service', version: '1.0.0' }.to_json
-end
-
-get '/quote' do
-  content_type :json
-  quote = QUOTES.sample
-  { quote: quote[:text], author: quote[:author], timestamp: Time.now.iso8601 }.to_json
-end
-
-get '/quotes' do
-  content_type :json
-  { quotes: QUOTES, count: QUOTES.size }.to_json
-end
-
-get '/quotes/:author' do
-  content_type :json
-  author_param = params['author'].downcase
-  matches = QUOTES.select { |q| q[:author].downcase.include?(author_param) }
-  if matches.empty?
-    status 404
-    { error: 'No quotes found for that author' }.to_json
-  else
-    { quotes: matches, count: matches.size }.to_json
-  end
-end
-
-get '/' do
-  content_type :json
-  {
-    service: 'Quote of the Day API',
-    version: '1.0.0',
-    endpoints: { health: 'GET /health', random_quote: 'GET /quote', all_quotes: 'GET /quotes', by_author: 'GET /quotes/:author' },
-    sandbox_id: ENV['SANDBOX_ID'] || 'unknown',
-    message: 'This service demonstrates a pre-initialized Ruby application in a warm sandbox. In production, this would be your actual application service.'
-  }.to_json
-end
-RUBY_SERVICE_EOF
-
-chmod +x /workspace/services/quote_service.rb
+cp /tmp/quote_service.rb /workspace/services/quote_service.rb
 
 # 5. Start the service in background
 echo "🌐 Starting quote service on port 4567..."
diff --git a/warm-sandbox-pool/sandbox_prep/quote_service.rb b/warm-sandbox-pool/sandbox_prep/quote_service.rb
index 9f648eb..6251bbc 100644
--- a/warm-sandbox-pool/sandbox_prep/quote_service.rb
+++ b/warm-sandbox-pool/sandbox_prep/quote_service.rb
@@ -6,6 +6,7 @@
 
 require 'sinatra'
 require 'json'
+require 'time'
 
 set :port, 4567
 set :bind, '0.0.0.0'
diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
index 3fecc93..b7d59ee 100644
--- a/warm-sandbox-pool/static/app.js
+++ b/warm-sandbox-pool/static/app.js
@@ -41,6 +41,9 @@ class PoolUI {
         // Update sandbox list
         this.renderSandboxes(poolStatus.sandboxes);
 
+        document.getElementById('halted-notice').style.display =
+            poolStatus.halted ? 'block' : 'none';
+
         // Check if pool is ready
         const wasReady = this.poolReady;
         this.poolReady = poolStatus.ready_count > 0;
@@ -73,8 +76,8 @@ class PoolUI {
             ? this.renderLogs(sandbox.init_log)
             : '';
 
-        const conversationLink = sandbox.conversation_id
-            ? `<a href="/conversations/${sandbox.conversation_id}" target="_blank" class="conversation-link">
+        const conversationLink = sandbox.conversation_url
+            ? `<a href="${this.escapeHtml(sandbox.conversation_url)}" target="_blank" class="conversation-link">
                    🔗 View Conversation
                </a>`
             : '';
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index ec3465d..3581a57 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -68,7 +68,11 @@ <h2>💬 Start a Conversation</h2>
                 <div id="waiting-state" class="waiting-state">
                     <div class="spinner"></div>
                     <p>Preparing sandbox pool...</p>
-                    <p class="waiting-subtext">This takes about 30-60 seconds on first start</p>
+                    <p class="waiting-subtext">This usually takes under a minute on first start</p>
+                    <p id="halted-notice" class="error-message" style="display: none;">
+                        ❌ Provisioning failed repeatedly, so refilling has stopped. See the
+                        controller's terminal output, fix the cause, and restart it.
+                    </p>
                 </div>
 
                 <div id="ready-state" class="ready-state" style="display: none;">
diff --git a/warm-sandbox-pool/test_structure.py b/warm-sandbox-pool/test_structure.py
index 3059308..42eafc1 100644
--- a/warm-sandbox-pool/test_structure.py
+++ b/warm-sandbox-pool/test_structure.py
@@ -4,6 +4,7 @@
 Run this before deploying to catch any missing files.
 """
 
+import subprocess
 from pathlib import Path
 
 
@@ -71,8 +72,27 @@ def check_structure():
     else:
         print("⚠️  Init script missing #!/bin/bash shebang")
 
+    syntax_ok = True
+    bash_check = subprocess.run(
+        ["bash", "-n", str(base / "sandbox_prep" / "init_ruby_service.sh")],
+        capture_output=True,
+        text=True,
+    )
+    if bash_check.returncode == 0:
+        print("✅ Init script passes bash -n")
+    else:
+        syntax_ok = False
+        print(f"❌ Init script syntax error:\n{bash_check.stderr}")
+
+    try:
+        compile((base / "pool_controller.py").read_text(), "pool_controller.py", "exec")
+        print("✅ pool_controller.py compiles")
+    except SyntaxError as e:
+        syntax_ok = False
+        print(f"❌ pool_controller.py syntax error: {e}")
+
     print("\n📊 Structure check complete!")
-    return len(missing) == 0
+    return len(missing) == 0 and syntax_ok
 
 
 if __name__ == "__main__":

From ec179f1e120bf5044072b2d9742e007afe9c5100 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 7 Oct 2026 19:20:12 +0000
Subject: [PATCH 5/9] warm-sandbox-pool: add a live activity view and correct
 the speed-up claims

Live view (extends the existing page, no new toolchain):
- Controller records an event feed: sandbox created, preparing, ready, pulled
  from the pool, claimed, failed, deleted, miss, halted, shutdown
- Stats strip: claims, average warm-up, average attach time
- "Claimed by conversations" list with per-sandbox warm-up, time waited in
  the pool, attach time and a link to the conversation
- Activity feed panel; the conversation form no longer hides itself when the
  pool is momentarily empty, it shows a refilling notice and disables Start

Fixes found while testing it:
- A sandbox pulled from the pool whose conversation failed to attach was
  stranded as ALLOCATED and never deleted; it is now deleted

Docs accuracy: measured a cold conversation start (12-26s, before any Ruby
install) against attaching to a warm sandbox (~10-12s). The pool removes
sandbox boot + init script from the wait, not the conversation start itself.
Replaced "instant"/"no delay" wording and added a table of what to expect.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md        |   4 +-
 warm-sandbox-pool/README.md            |  30 +++++--
 warm-sandbox-pool/pool_controller.py   | 107 ++++++++++++++++++++++++-
 warm-sandbox-pool/static/app.js        | 104 ++++++++++++++++++------
 warm-sandbox-pool/static/styles.css    |  95 ++++++++++++++++++++++
 warm-sandbox-pool/templates/index.html |  53 ++++++++++--
 6 files changed, 351 insertions(+), 42 deletions(-)

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index 15f2e04..de7d223 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -61,7 +61,7 @@ python pool_controller.py
    - Click "🚀 Start Conversation"
 
 4. **Observe the magic**:
-   - A ready sandbox is instantly pulled from the pool
+   - A ready sandbox is pulled from the pool immediately
    - The conversation attaches to it after a few seconds, with no sandbox boot or
      Ruby install wait
    - Click the conversation link to see your agent working
@@ -226,7 +226,7 @@ warm-sandbox-pool/
 You've successfully run the demo when:
 
 ✅ Pool shows 3 sandboxes in READY state\
-✅ You can start a conversation and get instant allocation\
+✅ You can start a conversation and a warm sandbox is allocated at once\
 ✅ The conversation link opens in OpenHands\
 ✅ The agent can interact with the pre-installed quote service\
 ✅ Pool automatically provisions a replacement sandbox
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
index aa7df8b..aaf6860 100644
--- a/warm-sandbox-pool/README.md
+++ b/warm-sandbox-pool/README.md
@@ -1,6 +1,6 @@
 # Warm Sandbox Pool
 
-Demonstrates maintaining a pool of pre-initialized "warm" sandboxes that late-bind to conversations on demand, eliminating startup delays for end users.
+Demonstrates maintaining a pool of pre-initialized "warm" sandboxes that late-bind to conversations on demand, taking sandbox startup and initialization out of the end user's wait.
 
 **This example demonstrates a technique for deploying Ruby-based applications** using OpenHands Cloud APIs, showing that custom images are not the only viable approach for handling initialization that takes more than a few seconds.
 
@@ -8,7 +8,7 @@ Demonstrates maintaining a pool of pre-initialized "warm" sandboxes that late-bi
 
 When applications have components that run outside the agent control loop and must be available on the system where the agent is running, a custom image is not the only mechanism for packaging these dependencies.
 
-Even when using custom images in OpenHands Enterprise, some scenarios require additional tasks to be completed on the running sandbox to make it ready for use. **If these tasks take more than a few seconds, the Warm Sandbox Pool technique eliminates the apparent delay an end-user would see** by preparing a pool of pre-initialized sandboxes that late-bind to conversations when an end-user begins to interact with the agent.
+Even when using custom images in OpenHands Enterprise, some scenarios require additional tasks to be completed on the running sandbox to make it ready for use. **If these tasks take more than a few seconds, the Warm Sandbox Pool technique removes that delay from what an end-user waits for** by preparing a pool of pre-initialized sandboxes that late-bind to conversations when an end-user begins to interact with the agent.
 
 This same approach can be used to install and prepare application services in sandboxes via API calls available in the OpenHands SaaS/Cloud platform, providing a viable alternative to custom images for your deployment needs.
 
@@ -18,7 +18,7 @@ Instead of waiting for sandbox provisioning and initialization every time a user
 
 1. **Maintains a pool** of pre-initialized sandboxes (e.g., 3 sandboxes)
 2. **Pre-installs dependencies** (Ruby, gems, application services) during sandbox preparation
-3. **Late-binds conversations** - when a user needs a sandbox, one is pulled from the pool instantly
+3. **Late-binds conversations** - when a user needs a sandbox, one is pulled from the pool with no boot or setup wait
 4. **Auto-refills** - when pool drops below threshold, new sandboxes are automatically provisioned and prepared in the background
 
 This is particularly valuable when:
@@ -100,6 +100,22 @@ Then open http://localhost:5000 in your browser.
 > If the controller is killed with SIGKILL it cannot clean up, so check your sandbox
 > list afterwards.
 
+### What to Expect (and what the pool does not speed up)
+
+The pool removes **sandbox boot plus your init script** from the user's wait. It does
+not remove the time OpenHands needs to start the conversation itself. Measured on one
+beta instance (your numbers will differ, and the web UI shows yours live):
+
+| | Time |
+|---|---|
+| Sandbox boot + init script, per pool sandbox ("warm-up", paid in the background) | about 10-25s, up to ~40s on a cold apt cache |
+| Starting a conversation cold (no `sandbox_id`), before any Ruby install | 12-26s |
+| Starting a conversation on a warm sandbox ("attach") | about 10-12s |
+
+So a cold start costs roughly *conversation start + warm-up*, and a warm start costs
+*conversation start*. The more expensive your init script, the bigger the win. For a
+cheap init script like this demo's, the saving is modest.
+
 ### What You'll See
 
 1. **Initial State**: "Preparing pool..." message while the sandboxes initialize
@@ -174,7 +190,11 @@ The `PoolController` class handles:
 
 ### Real-Time Updates
 
-The web UI uses Server-Sent Events (SSE) to stream pool state updates in real-time without polling.
+The web UI uses Server-Sent Events (SSE) to stream pool state to the browser every
+couple of seconds. Besides the sandbox cards it shows live stats (claims, average
+warm-up, average attach time), the sandboxes already claimed by conversations, and an
+activity feed of every pool event: created, ready, pulled from the pool, claimed,
+failed, deleted, refilling halted.
 
 ## Files
 
@@ -261,7 +281,7 @@ done
 echo "✅ Application ready"
 ```
 
-By pre-warming sandboxes with your application already running, agents can immediately interact with your services without the 30-60 second initialization delay on every conversation start.
+By pre-warming sandboxes with your application already running, agents can use your services as soon as the conversation starts, without waiting for sandbox boot and initialization (tens of seconds for this demo, more for heavier setups) on every conversation.
 
 ## Benefits vs. Custom Images
 
diff --git a/warm-sandbox-pool/pool_controller.py b/warm-sandbox-pool/pool_controller.py
index de9f0e0..ca38511 100755
--- a/warm-sandbox-pool/pool_controller.py
+++ b/warm-sandbox-pool/pool_controller.py
@@ -4,7 +4,7 @@
 
 Maintains a pool of pre-initialized OpenHands sandboxes with Ruby/Sinatra services
 already running. When users start conversations, sandboxes are pulled from the pool
-and attached instantly, with automatic refill.
+and attached without a boot or setup wait, with automatic refill.
 
 Usage:
     export OH_API_KEY=your_key_here
@@ -25,6 +25,7 @@
 import sys
 import threading
 import time
+from collections import deque
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -65,10 +66,19 @@ class PooledSandbox:
     ready_at: datetime | None = None
     allocated_at: datetime | None = None
     conversation_id: str | None = None
+    attach_seconds: float | None = None
     error_message: str | None = None
     init_log: list[str] = field(default_factory=list)
 
     def to_dict(self) -> dict:
+        warmup = (
+            (self.ready_at - self.created_at).total_seconds() if self.ready_at else None
+        )
+        idle = (
+            (self.allocated_at - self.ready_at).total_seconds()
+            if self.allocated_at and self.ready_at
+            else None
+        )
         return {
             "id": self.id,
             "state": self.state.value,
@@ -79,6 +89,9 @@ def to_dict(self) -> dict:
             if self.allocated_at
             else None,
             "conversation_id": self.conversation_id,
+            "warmup_seconds": warmup,
+            "idle_seconds": idle,
+            "attach_seconds": self.attach_seconds,
             "error_message": self.error_message,
             "init_log": self.init_log[-10:],  # Last 10 log lines
         }
@@ -111,6 +124,9 @@ def __init__(
         self.lock = threading.RLock()
         self.running = True
         self.consecutive_failures = 0
+        self.claim_misses = 0
+        self.events: deque[dict] = deque(maxlen=200)
+        self.event_seq = 0
 
         prep_dir = Path(__file__).parent / "sandbox_prep"
         self.init_script = self._load_file(prep_dir / "init_ruby_service.sh")
@@ -126,6 +142,20 @@ def _load_file(path: Path) -> str:
             raise FileNotFoundError(f"Sandbox prep file not found: {path}")
         return path.read_text()
 
+    def _record(self, kind: str, message: str, sandbox_id: str | None = None) -> None:
+        """Append to the activity feed shown in the web UI."""
+        with self.lock:
+            self.event_seq += 1
+            self.events.append(
+                {
+                    "seq": self.event_seq,
+                    "timestamp": datetime.now().isoformat(),
+                    "kind": kind,
+                    "sandbox_id": sandbox_id,
+                    "message": message,
+                }
+            )
+
     @property
     def halted(self) -> bool:
         """True once provisioning has failed too many times in a row."""
@@ -199,6 +229,7 @@ def _provision_and_init_sandbox(self) -> None:
             with self.lock:
                 self.all_sandboxes[sandbox_id] = sandbox
             logger.info(f"Sandbox {sandbox_id}: STARTING")
+            self._record("created", "Requested a new sandbox", sandbox_id)
 
             # 2. Poll until RUNNING
             sandbox = self._wait_until_running(sandbox, timeout=180)
@@ -206,6 +237,7 @@ def _provision_and_init_sandbox(self) -> None:
             # 3. Run initialization script
             sandbox.state = SandboxState.PREPARING
             logger.info(f"Sandbox {sandbox_id}: PREPARING (running init script)")
+            self._record("preparing", "Running the init script", sandbox_id)
             self._run_init_script(sandbox)
 
             # 4. Mark as ready and add to queue
@@ -219,15 +251,23 @@ def _provision_and_init_sandbox(self) -> None:
             if not accepted:
                 self._delete_sandbox(sandbox_id)
                 return
-            logger.info(
-                f"Sandbox {sandbox_id}: READY "
-                f"(took {(sandbox.ready_at - sandbox.created_at).seconds}s)"
+            warmup = (sandbox.ready_at - sandbox.created_at).total_seconds()
+            logger.info(f"Sandbox {sandbox_id}: READY (took {warmup:.0f}s)")
+            self._record(
+                "ready",
+                f"Warm and waiting in the pool (took {warmup:.0f}s)",
+                sandbox_id,
             )
 
         except Exception as e:
             logger.error(f"Failed to provision sandbox: {e}", exc_info=True)
             with self.lock:
                 self.consecutive_failures += 1
+            self._record(
+                "failed",
+                f"Provisioning failed: {str(e).splitlines()[0][:150]}",
+                sandbox.id if sandbox else None,
+            )
             if sandbox:
                 sandbox.state = SandboxState.FAILED
                 sandbox.error_message = str(e)
@@ -237,6 +277,10 @@ def _provision_and_init_sandbox(self) -> None:
                     f"{self.consecutive_failures} provisioning failures in a row: "
                     "refilling is halted. Fix the cause and restart the controller."
                 )
+                self._record(
+                    "halted",
+                    f"{self.consecutive_failures} failures in a row, refilling stopped",
+                )
 
     def _delete_sandbox(self, sandbox_id: str) -> None:
         """Best-effort delete so failed or unused sandboxes don't leak."""
@@ -249,6 +293,7 @@ def _delete_sandbox(self, sandbox_id: str) -> None:
             )
             resp.raise_for_status()
             logger.info(f"Sandbox {sandbox_id}: deleted")
+            self._record("deleted", "Sandbox deleted", sandbox_id)
         except Exception as e:
             logger.warning(f"Could not delete sandbox {sandbox_id}: {e}")
 
@@ -357,10 +402,25 @@ def get_ready_sandbox(self) -> PooledSandbox | None:
             sandbox = self.ready_queue.get_nowait()
             sandbox.state = SandboxState.ALLOCATED
             sandbox.allocated_at = datetime.now()
+            self._record(
+                "allocated", "Pulled from the pool for a new conversation", sandbox.id
+            )
             return sandbox
         except queue.Empty:
+            with self.lock:
+                self.claim_misses += 1
+            self._record(
+                "miss", "A conversation was requested but no sandbox was ready"
+            )
             return None
 
+    def abandon_claim(self, sandbox: PooledSandbox, error: Exception) -> None:
+        """Attaching failed after the sandbox left the pool: don't strand it."""
+        sandbox.state = SandboxState.FAILED
+        sandbox.error_message = str(error)
+        self._record("failed", f"Could not attach a conversation: {error}", sandbox.id)
+        self._delete_sandbox(sandbox.id)
+
     def get_pool_status(self) -> dict:
         """Get current pool status for the UI."""
         with self.lock:
@@ -368,6 +428,15 @@ def get_pool_status(self) -> dict:
                 [sb.to_dict() for sb in self.all_sandboxes.values()],
                 key=lambda x: x["created_at"],
             )
+            events = list(self.events)[-50:]
+            claim_misses = self.claim_misses
+
+        def average(values: list[float]) -> float | None:
+            return sum(values) / len(values) if values else None
+
+        attach_times = [
+            sb["attach_seconds"] for sb in sandboxes_list if sb["attach_seconds"]
+        ]
         for sb in sandboxes_list:
             if sb["conversation_id"]:
                 sb["conversation_url"] = (
@@ -379,12 +448,26 @@ def get_pool_status(self) -> dict:
             "threshold": self.threshold,
             "ready_count": self.ready_queue.qsize(),
             "halted": self.halted,
+            "stats": {
+                "claims": len(attach_times),
+                "claim_misses": claim_misses,
+                "avg_warmup_seconds": average(
+                    [
+                        sb["warmup_seconds"]
+                        for sb in sandboxes_list
+                        if sb["warmup_seconds"] is not None
+                    ]
+                ),
+                "avg_attach_seconds": average(attach_times),
+            },
+            "events": events,
             "sandboxes": sandboxes_list,
             "timestamp": datetime.now().isoformat(),
         }
 
     def attach_conversation(self, sandbox: PooledSandbox, message: str) -> str:
         """Attach a new conversation to the given sandbox."""
+        started = time.monotonic()
         payload = {
             "sandbox_id": sandbox.id,
             "initial_message": {
@@ -426,7 +509,19 @@ def attach_conversation(self, sandbox: PooledSandbox, message: str) -> str:
             raise TimeoutError(f"Start task {task_id} did not produce conversation ID")
 
         sandbox.conversation_id = conv_id
+        sandbox.attach_seconds = time.monotonic() - started
+        idle = (
+            (sandbox.allocated_at - sandbox.ready_at).total_seconds()
+            if sandbox.allocated_at and sandbox.ready_at
+            else 0
+        )
         logger.info(f"Conversation {conv_id} attached to sandbox {sandbox.id}")
+        self._record(
+            "claimed",
+            f"Conversation {conv_id[:8]} attached in {sandbox.attach_seconds:.1f}s "
+            f"(sandbox had been warm for {idle:.0f}s)",
+            sandbox.id,
+        )
         return conv_id
 
     def shutdown(self) -> None:
@@ -441,6 +536,9 @@ def shutdown(self) -> None:
         logger.info(
             f"Pool controller shutting down, deleting {len(leftovers)} sandbox(es)"
         )
+        self._record(
+            "shutdown", f"Shutting down, deleting {len(leftovers)} sandbox(es)"
+        )
         for sandbox_id in leftovers:
             self._delete_sandbox(sandbox_id)
 
@@ -515,6 +613,7 @@ def start_conversation():
         )
     except Exception as e:
         logger.error(f"Failed to attach conversation: {e}", exc_info=True)
+        pool_controller.abandon_claim(sandbox, e)
         return jsonify({"error": str(e)}), 500
 
 
diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
index b7d59ee..945c2c9 100644
--- a/warm-sandbox-pool/static/app.js
+++ b/warm-sandbox-pool/static/app.js
@@ -2,7 +2,10 @@
 
 class PoolUI {
     constructor() {
-        this.poolReady = false;
+        this.everReady = false;
+        this.readyCount = 0;
+        this.requestInFlight = false;
+        this.lastEventSeq = 0;
         this.eventSource = null;
         this.initialize();
     }
@@ -38,22 +41,84 @@ class PoolUI {
         document.getElementById('ready-count').textContent = poolStatus.ready_count;
         document.getElementById('threshold').textContent = poolStatus.threshold;
 
-        // Update sandbox list
-        this.renderSandboxes(poolStatus.sandboxes);
+        const allocated = poolStatus.sandboxes.filter(sb => sb.state === 'ALLOCATED');
+        this.renderSandboxes(poolStatus.sandboxes.filter(sb => sb.state !== 'ALLOCATED'));
+        this.renderClaimed(allocated);
+        this.renderStats(poolStatus.stats);
+        this.renderEvents(poolStatus.events);
 
         document.getElementById('halted-notice').style.display =
             poolStatus.halted ? 'block' : 'none';
 
-        // Check if pool is ready
-        const wasReady = this.poolReady;
-        this.poolReady = poolStatus.ready_count > 0;
-
-        // Toggle conversation interface visibility
-        if (this.poolReady && !wasReady) {
+        // Once the pool has been ready, keep the form visible: an empty pool
+        // between claim and refill is the interesting moment, not a reset.
+        this.readyCount = poolStatus.ready_count;
+        if (this.readyCount > 0 && !this.everReady) {
+            this.everReady = true;
             this.showConversationInterface();
-        } else if (!this.poolReady && wasReady) {
-            this.hideConversationInterface();
         }
+        const refilling = this.everReady && this.readyCount === 0 && !poolStatus.halted;
+        document.getElementById('refill-notice').style.display = refilling ? 'block' : 'none';
+        document.getElementById('ready-info').style.display = refilling ? 'none' : 'block';
+        this.syncStartButton();
+    }
+
+    syncStartButton() {
+        const button = document.getElementById('start-btn');
+        button.disabled = this.requestInFlight || this.readyCount === 0;
+    }
+
+    formatSeconds(value, digits = 0) {
+        return value === null || value === undefined ? '-' : `${value.toFixed(digits)}s`;
+    }
+
+    renderStats(stats) {
+        document.getElementById('claim-count').textContent = stats.claims;
+        document.getElementById('avg-warmup').textContent =
+            this.formatSeconds(stats.avg_warmup_seconds);
+        document.getElementById('avg-attach').textContent =
+            this.formatSeconds(stats.avg_attach_seconds, 1);
+    }
+
+    renderClaimed(sandboxes) {
+        const container = document.getElementById('claimed-list');
+        if (sandboxes.length === 0) {
+            container.innerHTML = '<p class="empty-note">Nothing claimed yet.</p>';
+            return;
+        }
+        container.innerHTML = sandboxes.slice().reverse().map(sb => {
+            const link = sb.conversation_url
+                ? `<a href="${this.escapeHtml(sb.conversation_url)}" target="_blank" class="conversation-link">🔗 Conversation</a>`
+                : '<span class="conversation-link">attaching...</span>';
+            return `
+                <div class="claimed-row">
+                    <code>${this.shortId(sb.id)}</code>${link}
+                    <div class="claimed-timing">
+                        warm ${this.formatSeconds(sb.warmup_seconds)} ·
+                        waited in pool ${this.formatSeconds(sb.idle_seconds)} ·
+                        attach ${this.formatSeconds(sb.attach_seconds, 1)}
+                    </div>
+                </div>`;
+        }).join('');
+    }
+
+    renderEvents(events) {
+        const last = events.length ? events[events.length - 1].seq : 0;
+        if (last === this.lastEventSeq) return;
+        this.lastEventSeq = last;
+
+        const emojis = {
+            created: '➕', preparing: '🛠️', ready: '🟢', allocated: '🟦',
+            claimed: '✅', failed: '⚠️', deleted: '🗑️', halted: '⛔',
+            miss: '🙅', shutdown: '🛑'
+        };
+        document.getElementById('event-log').innerHTML = events.slice().reverse().map(e => `
+            <div class="event-row event-kind-${this.escapeHtml(e.kind)}">
+                <span class="event-time">${this.escapeHtml(e.timestamp.substring(11, 19))}</span>
+                <span>${emojis[e.kind] || '•'}</span>
+                <span class="event-sandbox">${e.sandbox_id ? this.shortId(e.sandbox_id) : ''}</span>
+                <span class="event-message">${this.escapeHtml(e.message)}</span>
+            </div>`).join('');
     }
 
     renderSandboxes(sandboxes) {
@@ -147,11 +212,6 @@ class PoolUI {
         document.getElementById('ready-state').style.display = 'block';
     }
 
-    hideConversationInterface() {
-        document.getElementById('waiting-state').style.display = 'block';
-        document.getElementById('ready-state').style.display = 'none';
-    }
-
     setupConversationForm() {
         const form = document.getElementById('message-input');
         const button = document.getElementById('start-btn');
@@ -168,13 +228,8 @@ class PoolUI {
                 return;
             }
 
-            if (!this.poolReady) {
-                alert('Pool is not ready yet. Please wait for at least one sandbox to be ready.');
-                return;
-            }
-
-            // Disable button during request
-            button.disabled = true;
+            this.requestInFlight = true;
+            this.syncStartButton();
             button.textContent = '⏳ Starting...';
 
             try {
@@ -202,7 +257,8 @@ class PoolUI {
                 console.error('Error starting conversation:', error);
                 this.showResult({ error: error.message }, true);
             } finally {
-                button.disabled = false;
+                this.requestInFlight = false;
+                this.syncStartButton();
                 button.textContent = '🚀 Start Conversation';
             }
         });
diff --git a/warm-sandbox-pool/static/styles.css b/warm-sandbox-pool/static/styles.css
index 79914f0..dbf95f8 100644
--- a/warm-sandbox-pool/static/styles.css
+++ b/warm-sandbox-pool/static/styles.css
@@ -113,6 +113,101 @@ header .subtitle {
     color: var(--success-color);
 }
 
+.stats-note {
+    margin: -8px 0 20px;
+    font-size: 0.8rem;
+    color: var(--text-secondary);
+}
+
+.section-title {
+    font-size: 1rem;
+    margin: 0 0 8px;
+    color: var(--text-primary);
+}
+
+.empty-note {
+    color: var(--text-secondary);
+    font-size: 0.875rem;
+    text-align: center;
+    padding: 8px;
+}
+
+/* Claimed sandboxes */
+.claimed-list {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    margin-bottom: 20px;
+    max-height: 240px;
+    overflow-y: auto;
+}
+
+.claimed-row {
+    padding: 10px 12px;
+    border: 1px solid var(--border-color);
+    border-left: 4px solid var(--primary-color);
+    border-radius: 6px;
+    font-size: 0.875rem;
+}
+
+.claimed-row .conversation-link {
+    margin: 0 0 0 8px;
+}
+
+.claimed-timing {
+    color: var(--text-secondary);
+    margin-top: 4px;
+}
+
+/* Activity feed */
+.activity-panel {
+    margin-bottom: 20px;
+}
+
+.event-log {
+    max-height: 320px;
+    overflow-y: auto;
+    font-family: 'Courier New', monospace;
+    font-size: 0.8rem;
+}
+
+.event-row {
+    display: grid;
+    grid-template-columns: 70px 28px 140px 1fr;
+    gap: 8px;
+    padding: 4px 0;
+    border-bottom: 1px solid var(--border-color);
+}
+
+.event-time,
+.event-sandbox {
+    color: var(--text-secondary);
+}
+
+.event-kind-claimed .event-message {
+    color: var(--success-color);
+    font-weight: bold;
+}
+
+.event-kind-failed .event-message,
+.event-kind-halted .event-message,
+.event-kind-miss .event-message {
+    color: var(--danger-color);
+}
+
+.refill-notice {
+    padding: 10px 12px;
+    margin-bottom: 12px;
+    border-radius: 8px;
+    background: #fef3c7;
+    font-size: 0.875rem;
+}
+
+.btn-primary:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+}
+
 /* Sandbox List */
 .sandbox-list {
     display: flex;
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index 3581a57..6f14857 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -32,10 +32,36 @@ <h2>📦 Sandbox Pool</h2>
                     </div>
                 </div>
 
+                <div class="pool-stats" id="claim-stats">
+                    <div class="stat">
+                        <span class="stat-label">Claims:</span>
+                        <span class="stat-value" id="claim-count">0</span>
+                    </div>
+                    <div class="stat">
+                        <span class="stat-label">Avg warm-up:</span>
+                        <span class="stat-value" id="avg-warmup">-</span>
+                    </div>
+                    <div class="stat">
+                        <span class="stat-label">Avg attach:</span>
+                        <span class="stat-value" id="avg-attach">-</span>
+                    </div>
+                </div>
+                <p class="stats-note">
+                    <strong>Warm-up</strong> is the sandbox boot plus init script that a cold
+                    start would add to each conversation's wait. <strong>Attach</strong> is the
+                    conversation start itself, which happens either way.
+                </p>
+
+                <h3 class="section-title">In the pool</h3>
                 <div id="sandbox-list" class="sandbox-list">
                     <!-- Sandbox cards will be inserted here -->
                 </div>
 
+                <h3 class="section-title">Claimed by conversations</h3>
+                <div id="claimed-list" class="claimed-list">
+                    <p class="empty-note">Nothing claimed yet.</p>
+                </div>
+
                 <div class="pool-legend">
                     <h3>Status Legend</h3>
                     <div class="legend-item">
@@ -65,22 +91,28 @@ <h3>Status Legend</h3>
             <div class="panel conversation-panel">
                 <h2>💬 Start a Conversation</h2>
 
+                <p id="halted-notice" class="error-message" style="display: none;">
+                    ❌ Provisioning failed repeatedly, so refilling has stopped. See the
+                    controller's terminal output, fix the cause, and restart it.
+                </p>
+
                 <div id="waiting-state" class="waiting-state">
                     <div class="spinner"></div>
                     <p>Preparing sandbox pool...</p>
                     <p class="waiting-subtext">This usually takes under a minute on first start</p>
-                    <p id="halted-notice" class="error-message" style="display: none;">
-                        ❌ Provisioning failed repeatedly, so refilling has stopped. See the
-                        controller's terminal output, fix the cause, and restart it.
-                    </p>
                 </div>
 
                 <div id="ready-state" class="ready-state" style="display: none;">
-                    <div class="info-box">
+                    <div class="info-box" id="ready-info">
                         <p><strong>✨ Pool is ready!</strong></p>
-                        <p>Type a message below to start an OpenHands conversation. A pre-warmed sandbox with Ruby and Sinatra already installed will be allocated instantly.</p>
+                        <p>Type a message below to start an OpenHands conversation. A pre-warmed sandbox with Ruby and Sinatra already installed will be allocated to your conversation right away.</p>
                     </div>
 
+                    <p id="refill-notice" class="refill-notice" style="display: none;">
+                        ⏳ No warm sandbox is ready right now. The pool is refilling and you
+                        can start the next conversation as soon as one turns green.
+                    </p>
+
                     <div class="conversation-form">
                         <label for="message-input">Your message to the agent:</label>
                         <textarea
@@ -101,7 +133,7 @@ <h2>💬 Start a Conversation</h2>
 
                 <div class="info-section">
                     <h3>About This Demo</h3>
-                    <p>This demonstrates the <strong>Warm Sandbox Pool</strong> technique for eliminating initialization delays when using OpenHands agents.</p>
+                    <p>This demonstrates the <strong>Warm Sandbox Pool</strong> technique for taking sandbox startup and initialization out of the wait when using OpenHands agents.</p>
 
                     <h4>What's Pre-Installed:</h4>
                     <ul>
@@ -124,6 +156,13 @@ <h4>Try These Commands:</h4>
                 </div>
             </div>
         </div>
+
+        <div class="panel activity-panel">
+            <h2>📜 Live Activity</h2>
+            <div id="event-log" class="event-log">
+                <p class="empty-note">Waiting for activity...</p>
+            </div>
+        </div>
     </div>
 
     <footer>

From ecb63c504efaac348ec738ba095a7adbcd6fd29f Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 7 Oct 2026 19:33:37 +0000
Subject: [PATCH 6/9] warm-sandbox-pool: document running it from an OpenHands
 sandbox

Explain how an agent can run the example on a sandbox work port
(HOST=0.0.0.0 PORT=12000), hand the user the work URL to watch the live UI,
and stop the controller afterwards.

Verified through a real work URL: the page, the SSE stream (frames arrive
every ~2s, unbuffered) and POST /api/conversation/start all work via the proxy.

The UI has no login, so the docs carry an explicit security note: anyone with
the URL can start a conversation with an arbitrary prompt on the user's
account. Acceptable for a brief demo with an unguessable URL; not for anything
long-lived.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md |  5 ++++
 warm-sandbox-pool/README.md     | 45 +++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index de7d223..d38671a 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -24,6 +24,11 @@ uv pip install -e .
 
 ## Run the Demo
 
+> **Running this from an OpenHands sandbox?** Start the controller with
+> `HOST=0.0.0.0 PORT=12000` and open the sandbox's `work-1-…` URL to watch the web UI
+> from your browser. See "Run It From an OpenHands Sandbox" in `README.md`, including
+> its security note (the UI has no login).
+
 > **This creates real sandboxes.** The controller starts `POOL_SIZE` (default 3)
 > sandboxes right away and keeps refilling the pool. For a first try use
 > `POOL_SIZE=1 POOL_THRESHOLD=1`. Press Ctrl-C to stop: unused pool sandboxes are
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
index aaf6860..af15549 100644
--- a/warm-sandbox-pool/README.md
+++ b/warm-sandbox-pool/README.md
@@ -100,6 +100,51 @@ Then open http://localhost:5000 in your browser.
 > If the controller is killed with SIGKILL it cannot clean up, so check your sandbox
 > list afterwards.
 
+### Run It From an OpenHands Sandbox and Watch the Web UI
+
+You can run this example inside an OpenHands sandbox (for example, ask an OpenHands
+agent to "run the warm-sandbox-pool example") and watch the web UI from your own
+browser. OpenHands sandboxes publish app ports as "work" URLs, so the agent starts the
+controller on one of those ports, binds it to all interfaces, and gives you the link.
+
+Steps for the agent (or for you, in a sandbox terminal):
+
+1. Pick a published port. The sandbox's environment lists its work URLs, for example
+   `https://work-1-<id>-runtime.<domain>/` for port 12000 and
+   `https://work-2-<id>-runtime.<domain>/` for port 12001.
+2. Start the controller on that port, bound to `0.0.0.0` (the default `127.0.0.1` is
+   not reachable through the work URL):
+
+   ```bash
+   export OH_API_KEY=your_api_key_here
+   OH_API_BASE=https://app.all-hands.dev POOL_SIZE=3 HOST=0.0.0.0 PORT=12000 \
+     python pool_controller.py
+   ```
+
+3. Give the user the matching work URL (`https://work-1-<id>-runtime.<domain>/` for
+   port 12000). They will see the pool fill, can claim a sandbox with Start
+   Conversation, and can watch the refill and the activity feed live.
+4. When the user is done, stop the controller (Ctrl-C or `kill <pid>`; SIGTERM also
+   works). It deletes the unused pool sandboxes. Sandboxes already claimed by
+   conversations are left running, so delete those too if you do not need them.
+
+This was verified through a real work URL: the page, the live stream, and starting a
+conversation all work through the proxy.
+
+> **Security: read this before sharing the link.** The web UI has **no login**.
+> Anyone who has the work URL can open it, and can use **Start Conversation** to run an
+> agent with **any prompt you let them type**, on **your** account (your credits, and
+> any secrets your account makes available to conversations). They cannot reach the
+> sandboxes directly, because session keys never leave the controller, but starting a
+> conversation is still real agent execution. That is an acceptable risk for a short
+> demo with an unguessable URL, so treat it as one:
+>
+> - Run it briefly and stop it when you are done. Do not leave it running.
+> - Do not post the URL publicly.
+> - Keep `POOL_SIZE` small (the default of 3 is fine). Note that each claim triggers a
+>   refill, so the total number of sandboxes grows by one per conversation started.
+> - For anything longer-lived, put authentication in front of it first.
+
 ### What to Expect (and what the pool does not speed up)
 
 The pool removes **sandbox boot plus your init script** from the user's wait. It does

From 85f5a66296cd9ccf8979bfaa87603fa46f359a25 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 7 Oct 2026 19:41:38 +0000
Subject: [PATCH 7/9] warm-sandbox-pool: gate the UI behind an access code and
 show refill progress

Access code
- The controller generates a random 10-character code at startup (no look-alike
  characters), prints it in its output, and the browser signs in by pasting it.
- Everything except the sign-in page and its static assets returns 401 without
  the session cookie: the dashboard, the status API, the SSE stream and
  POST /api/conversation/start. Comparison is constant-time; the code and the
  session key live only in memory, so a restart invalidates both. An open page
  notices the 401 and falls back to the sign-in page.
- Docs: the sandbox work-URL section now tells the agent to read the code from
  the controller's output and hand the user the link and the code, and the
  security note describes what the code does and does not protect.

Refill visibility
- New line under the stats: "Refilling: N in progress (R ready, target T)", or
  an explanation of why nothing is happening ("2 of 3 ready. A refill starts
  when ready drops below 2.").
- The feed now records why a refill started: "1 ready is below the threshold
  of 2: starting 2 sandbox(es) to get back to 3".
- The claim success box no longer says the pool refills immediately, which was
  not true when ready is still at the threshold.

Verified on beta through a real work URL: unauthenticated requests get 401
(including trailing-slash and double-slash variants), a wrong code gets 403,
a lowercase correct code signs in, claims work through the session, and a
controller restart sends an open page back to sign-in. Test sandboxes and
conversations were deleted.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md        | 18 +++++---
 warm-sandbox-pool/README.md            | 53 ++++++++++++++---------
 warm-sandbox-pool/pool_controller.py   | 59 +++++++++++++++++++++++---
 warm-sandbox-pool/static/app.js        | 31 +++++++++++++-
 warm-sandbox-pool/static/login.js      | 19 +++++++++
 warm-sandbox-pool/static/styles.css    | 50 ++++++++++++++++++++++
 warm-sandbox-pool/templates/index.html |  2 +
 warm-sandbox-pool/templates/login.html | 35 +++++++++++++++
 warm-sandbox-pool/test_structure.py    |  2 +
 9 files changed, 237 insertions(+), 32 deletions(-)
 create mode 100644 warm-sandbox-pool/static/login.js
 create mode 100644 warm-sandbox-pool/templates/login.html

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index d38671a..4ad428f 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -26,8 +26,9 @@ uv pip install -e .
 
 > **Running this from an OpenHands sandbox?** Start the controller with
 > `HOST=0.0.0.0 PORT=12000` and open the sandbox's `work-1-…` URL to watch the web UI
-> from your browser. See "Run It From an OpenHands Sandbox" in `README.md`, including
-> its security note (the UI has no login).
+> from your browser. Read the `ACCESS CODE:` line from the controller's output and give
+> it to the user to paste into the page. See "Run It From an OpenHands Sandbox" in
+> `README.md`, including its security note.
 
 > **This creates real sandboxes.** The controller starts `POOL_SIZE` (default 3)
 > sandboxes right away and keeps refilling the pool. For a first try use
@@ -43,19 +44,26 @@ python pool_controller.py
 
 # You should see:
 # INFO pool_controller: Pool controller initialized: size=3, threshold=2
+# INFO pool_controller: Initial pool fill to 3 sandboxes
 # INFO pool_controller: Pool manager thread started
-# INFO pool_controller: Starting web server on port 5000
+# INFO pool_controller: Starting web server on 127.0.0.1:5000
 # INFO pool_controller: Open http://localhost:5000 in your browser
+# INFO pool_controller: ACCESS CODE: XXXXX-XXXXX  (paste it into the web page to sign in)
 ```
 
 ## Use the Demo (2-3 minutes)
 
-1. **Open http://localhost:5000** in your browser
+1. **Open http://localhost:5000** in your browser and paste the access code from the
+   controller's output (the `ACCESS CODE:` line) into the sign-in page
 
 2. **Watch the pool initialize**:
    - You'll see "Preparing pool..." message
    - 3 sandboxes will start initializing (roughly 10-30 seconds each)
    - Watch them progress: 🔴 STARTING → 🟡 PREPARING → 🟢 READY
+   - A line under the stats says what the pool is doing, for example
+     "Refilling: 2 in progress (1 ready, target 3)" or "2 of 3 ready. A refill starts
+     when ready drops below 2." (the pool only refills once ready drops *below* the
+     threshold, and checks every 5 seconds)
 
 3. **Start a conversation**:
    - Once at least one sandbox is READY, the conversation UI appears
@@ -128,7 +136,7 @@ Customize via environment variables:
 export OH_API_KEY=your_key
 export OH_API_BASE=https://app.all-hands.dev  # or your instance
 export PORT=5000                               # Web UI port
-export HOST=127.0.0.1                          # UI has no auth; keep it local
+export HOST=127.0.0.1                          # 0.0.0.0 only for a sandbox work URL
 
 # Pool sizing
 export POOL_SIZE=3          # How many ready sandboxes to maintain
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
index af15549..7886d74 100644
--- a/warm-sandbox-pool/README.md
+++ b/warm-sandbox-pool/README.md
@@ -90,7 +90,9 @@ export OH_API_KEY=your_api_key_here
 python pool_controller.py
 ```
 
-Then open http://localhost:5000 in your browser.
+Then open http://localhost:5000 in your browser. The controller prints a random
+**access code** when it starts (look for `ACCESS CODE:` in its output). Paste it into
+the page to sign in. Nothing is served without it, and a restart issues a new code.
 
 > **Heads up: this creates real sandboxes.** The controller immediately starts
 > `POOL_SIZE` sandboxes (default 3) and keeps topping the pool up as you use them.
@@ -121,29 +123,39 @@ Steps for the agent (or for you, in a sandbox terminal):
      python pool_controller.py
    ```
 
-3. Give the user the matching work URL (`https://work-1-<id>-runtime.<domain>/` for
-   port 12000). They will see the pool fill, can claim a sandbox with Start
-   Conversation, and can watch the refill and the activity feed live.
+3. Read the access code from the controller's output (the line starting
+   `ACCESS CODE:`), then give the user **both** the matching work URL
+   (`https://work-1-<id>-runtime.<domain>/` for port 12000) and the code. They paste
+   the code into the page to sign in, then watch the pool fill, claim a sandbox with
+   Start Conversation, and follow the refill and the activity feed live.
 4. When the user is done, stop the controller (Ctrl-C or `kill <pid>`; SIGTERM also
    works). It deletes the unused pool sandboxes. Sandboxes already claimed by
    conversations are left running, so delete those too if you do not need them.
 
-This was verified through a real work URL: the page, the live stream, and starting a
-conversation all work through the proxy.
+This was verified through a real work URL: sign-in, the page, the live stream, and
+starting a conversation all work through the proxy.
 
-> **Security: read this before sharing the link.** The web UI has **no login**.
-> Anyone who has the work URL can open it, and can use **Start Conversation** to run an
-> agent with **any prompt you let them type**, on **your** account (your credits, and
-> any secrets your account makes available to conversations). They cannot reach the
-> sandboxes directly, because session keys never leave the controller, but starting a
-> conversation is still real agent execution. That is an acceptable risk for a short
-> demo with an unguessable URL, so treat it as one:
+> **Security: what the access code does and does not protect.** A work URL is reachable
+> by anyone who has it, so the controller gates **everything** (the page, the status
+> API, the live stream, and Start Conversation) behind a random one-time access code.
+> Without the code, a visitor sees only the sign-in page. The code is 10 characters
+> from a 32-character alphabet, is generated fresh on every start, lives only in the
+> controller's memory, and is checked in constant time.
 >
+> What it does not do: whoever has the URL **and** the code can use **Start
+> Conversation** to run an agent with **any prompt they type**, on **your** account
+> (your credits, and any secrets your account makes available to conversations).
+> Sandboxes themselves are never exposed, because session keys stay in the controller.
+> The rules for a safe demo:
+>
+> - Give the code only to the person who should have it. It is printed in the
+>   controller's output, so do not paste that output into public places.
 > - Run it briefly and stop it when you are done. Do not leave it running.
-> - Do not post the URL publicly.
-> - Keep `POOL_SIZE` small (the default of 3 is fine). Note that each claim triggers a
->   refill, so the total number of sandboxes grows by one per conversation started.
-> - For anything longer-lived, put authentication in front of it first.
+> - Keep `POOL_SIZE` small (the default of 3 is fine). Each claim can trigger a refill,
+>   so the total number of sandboxes grows by one per conversation started.
+> - This is a demo gate, not a production login: there are no user accounts and no
+>   rate limiting on guesses. For anything longer-lived, put real authentication in
+>   front of it.
 
 ### What to Expect (and what the pool does not speed up)
 
@@ -187,9 +199,10 @@ Environment variables:
 - `MAX_FAILURES`: Stop refilling after this many provisioning failures in a row
   (default: `3`). A failed sandbox is deleted immediately, so a broken init script
   cannot silently create sandboxes forever.
-- `HOST`: Address the web UI binds to (default: `127.0.0.1`). The UI has no
-  authentication and can start conversations with your API key, so only widen this
-  on a trusted network.
+- `HOST`: Address the web UI binds to (default: `127.0.0.1`). Use `0.0.0.0` to reach
+  it through an OpenHands sandbox work URL. The UI can start conversations with your
+  API key, so it is gated by the access code the controller prints at startup; see
+  the security note above.
 - `PORT`: Web server port (default: `5000`)
 
 ### Testing the Ruby Service
diff --git a/warm-sandbox-pool/pool_controller.py b/warm-sandbox-pool/pool_controller.py
index ca38511..4f4bbe9 100755
--- a/warm-sandbox-pool/pool_controller.py
+++ b/warm-sandbox-pool/pool_controller.py
@@ -10,17 +10,21 @@
     export OH_API_KEY=your_key_here
     python pool_controller.py
 
-Then open http://localhost:5000 in your browser.
+Then open http://localhost:5000 in your browser. The controller prints a random
+access code when it starts; paste it into the web page to sign in. Nothing is served
+without it.
 
 On exit (Ctrl-C / SIGTERM) every sandbox that is still in the pool is deleted.
 Sandboxes already handed to a conversation are left alone.
 """
 
 import argparse
+import hmac
 import json
 import logging
 import os
 import queue
+import secrets
 import signal
 import sys
 import threading
@@ -32,7 +36,7 @@
 from pathlib import Path
 
 import requests
-from flask import Flask, jsonify, render_template, request
+from flask import Flask, jsonify, render_template, request, session
 
 
 # Configure logging
@@ -171,6 +175,9 @@ def _pool_manager_loop(self) -> None:
         """Background thread that maintains the pool at the target size."""
         # Initial fill
         logger.info(f"Initial pool fill to {self.pool_size} sandboxes")
+        self._record(
+            "refill", f"Filling the pool: starting {self.pool_size} sandbox(es)"
+        )
         for _ in range(self.pool_size):
             self._provision_sandbox()
 
@@ -187,6 +194,12 @@ def _pool_manager_loop(self) -> None:
                         f"Pool below threshold ({ready_count} < {self.threshold}), "
                         f"provisioning {needed} sandbox(es)"
                     )
+                    self._record(
+                        "refill",
+                        f"{ready_count} ready is below the threshold of "
+                        f"{self.threshold}: starting {needed} sandbox(es) to get "
+                        f"back to {self.pool_size}",
+                    )
                     for _ in range(needed):
                         self._provision_sandbox()
 
@@ -545,14 +558,48 @@ def shutdown(self) -> None:
 
 # Flask Application
 app = Flask(__name__)
+app.secret_key = secrets.token_hex(32)
+app.config.update(SESSION_COOKIE_HTTPONLY=True, SESSION_COOKIE_SAMESITE="Lax")
 
 pool_controller: PoolController | None = None
 
+# No 0/O or 1/I so the code survives being read out or retyped.
+CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+
+def generate_access_code() -> str:
+    chars = [secrets.choice(CODE_ALPHABET) for _ in range(10)]
+    return "".join(chars[:5]) + "-" + "".join(chars[5:])
+
+
+ACCESS_CODE = generate_access_code()
+
+
+@app.before_request
+def require_access_code():
+    if request.endpoint in ("index", "login", "static"):
+        return None
+    if not session.get("authenticated"):
+        return jsonify({"error": "Access code required"}), 401
+    return None
+
 
 @app.route("/")
 def index():
-    """Serve the main UI."""
-    return render_template("index.html")
+    """Serve the main UI, or the sign-in page until the access code is entered."""
+    if session.get("authenticated"):
+        return render_template("index.html")
+    return render_template("login.html")
+
+
+@app.route("/api/login", methods=["POST"])
+def login():
+    supplied = str((request.get_json(silent=True) or {}).get("code", ""))
+    supplied = supplied.strip().upper()
+    if not hmac.compare_digest(supplied.encode(), ACCESS_CODE.encode()):
+        return jsonify({"error": "That access code is not right"}), 403
+    session["authenticated"] = True
+    return jsonify({"ok": True})
 
 
 @app.route("/api/pool/status")
@@ -656,7 +703,8 @@ def parse_args():
         "--host",
         default=os.environ.get("HOST", "127.0.0.1"),
         help="Web server bind address (env: HOST, default: 127.0.0.1). "
-        "The UI has no authentication; only widen this on a trusted network.",
+        "Use 0.0.0.0 to reach the UI through an OpenHands sandbox work URL. "
+        "The UI is gated by the access code printed at startup.",
     )
     p.add_argument(
         "--init-timeout",
@@ -699,6 +747,7 @@ def main():
 
     logger.info(f"Starting web server on {args.host}:{args.port}")
     logger.info(f"Open http://localhost:{args.port} in your browser")
+    logger.info(f"ACCESS CODE: {ACCESS_CODE}  (paste it into the web page to sign in)")
     try:
         app.run(host=args.host, port=args.port, debug=False, threaded=True)
     finally:
diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
index 945c2c9..f87331e 100644
--- a/warm-sandbox-pool/static/app.js
+++ b/warm-sandbox-pool/static/app.js
@@ -26,6 +26,11 @@ class PoolUI {
 
         this.eventSource.onerror = (error) => {
             console.error('EventSource error:', error);
+            // A 401 (e.g. the controller restarted and issued a new access code)
+            // looks like a plain stream error, so ask the API directly.
+            fetch('/api/pool/status').then(response => {
+                if (response.status === 401) window.location.reload();
+            });
             // Try to reconnect after 5 seconds
             setTimeout(() => {
                 if (this.eventSource.readyState === EventSource.CLOSED) {
@@ -45,6 +50,7 @@ class PoolUI {
         this.renderSandboxes(poolStatus.sandboxes.filter(sb => sb.state !== 'ALLOCATED'));
         this.renderClaimed(allocated);
         this.renderStats(poolStatus.stats);
+        this.renderRefillLine(poolStatus);
         this.renderEvents(poolStatus.events);
 
         document.getElementById('halted-notice').style.display =
@@ -80,6 +86,26 @@ class PoolUI {
             this.formatSeconds(stats.avg_attach_seconds, 1);
     }
 
+    renderRefillLine(status) {
+        const inProgress = status.sandboxes.filter(
+            sb => sb.state === 'STARTING' || sb.state === 'PREPARING'
+        ).length;
+        let text;
+        if (status.halted) {
+            text = '⛔ Refilling stopped after repeated failures';
+        } else if (inProgress > 0) {
+            const verb = this.everReady || status.stats.claims > 0 ? 'Refilling' : 'Filling';
+            text = `🔄 ${verb}: ${inProgress} in progress (${status.ready_count} ready, target ${status.pool_size})`;
+        } else if (status.ready_count >= status.pool_size) {
+            text = `✅ Pool is full: ${status.ready_count} ready`;
+        } else if (status.ready_count >= status.threshold) {
+            text = `⏸ ${status.ready_count} of ${status.pool_size} ready. A refill starts when ready drops below ${status.threshold}.`;
+        } else {
+            text = '🔄 Below the threshold: a refill starts within a few seconds';
+        }
+        document.getElementById('refill-line').textContent = text;
+    }
+
     renderClaimed(sandboxes) {
         const container = document.getElementById('claimed-list');
         if (sandboxes.length === 0) {
@@ -110,7 +136,7 @@ class PoolUI {
         const emojis = {
             created: '➕', preparing: '🛠️', ready: '🟢', allocated: '🟦',
             claimed: '✅', failed: '⚠️', deleted: '🗑️', halted: '⛔',
-            miss: '🙅', shutdown: '🛑'
+            miss: '🙅', shutdown: '🛑', refill: '🔄'
         };
         document.getElementById('event-log').innerHTML = events.slice().reverse().map(e => `
             <div class="event-row event-kind-${this.escapeHtml(e.kind)}">
@@ -283,7 +309,8 @@ class PoolUI {
                     🔗 Open Conversation in OpenHands
                 </a>
                 <p style="margin-top: 16px; font-size: 0.875rem; color: #6b7280;">
-                    The pool will automatically provision a new sandbox to refill the allocated slot.
+                    The pool refills automatically once its ready sandboxes drop below
+                    the threshold. Watch the activity feed below.
                 </p>
             `;
         }
diff --git a/warm-sandbox-pool/static/login.js b/warm-sandbox-pool/static/login.js
new file mode 100644
index 0000000..dfede62
--- /dev/null
+++ b/warm-sandbox-pool/static/login.js
@@ -0,0 +1,19 @@
+document.getElementById('login-form').addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const error = document.getElementById('login-error');
+    error.style.display = 'none';
+
+    const response = await fetch('/api/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code: document.getElementById('code-input').value })
+    });
+
+    if (response.ok) {
+        window.location.reload();
+        return;
+    }
+    const data = await response.json();
+    error.textContent = data.error;
+    error.style.display = 'block';
+});
diff --git a/warm-sandbox-pool/static/styles.css b/warm-sandbox-pool/static/styles.css
index dbf95f8..754d461 100644
--- a/warm-sandbox-pool/static/styles.css
+++ b/warm-sandbox-pool/static/styles.css
@@ -119,6 +119,52 @@ header .subtitle {
     color: var(--text-secondary);
 }
 
+.refill-line {
+    margin: 0 0 16px;
+    padding: 8px 12px;
+    background: var(--bg-light);
+    border-radius: 8px;
+    font-size: 0.9rem;
+    font-weight: 500;
+}
+
+.login-panel {
+    max-width: 480px;
+    margin: 0 auto 20px;
+}
+
+.login-panel p {
+    margin-bottom: 16px;
+    color: var(--text-secondary);
+}
+
+.login-panel .error-message {
+    color: var(--danger-color);
+    margin: 16px 0 0;
+}
+
+.login-form {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+
+.login-form input {
+    flex: 1;
+    padding: 12px;
+    border: 2px solid var(--border-color);
+    border-radius: 8px;
+    font-family: 'Courier New', monospace;
+    font-size: 1.25rem;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+}
+
+.login-form button {
+    width: auto;
+    padding: 12px 24px;
+}
+
 .section-title {
     font-size: 1rem;
     margin: 0 0 8px;
@@ -184,6 +230,10 @@ header .subtitle {
     color: var(--text-secondary);
 }
 
+.event-kind-refill .event-message {
+    color: var(--primary-color);
+}
+
 .event-kind-claimed .event-message {
     color: var(--success-color);
     font-weight: bold;
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index 6f14857..3559eee 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -52,6 +52,8 @@ <h2>📦 Sandbox Pool</h2>
                     conversation start itself, which happens either way.
                 </p>
 
+                <p id="refill-line" class="refill-line"></p>
+
                 <h3 class="section-title">In the pool</h3>
                 <div id="sandbox-list" class="sandbox-list">
                     <!-- Sandbox cards will be inserted here -->
diff --git a/warm-sandbox-pool/templates/login.html b/warm-sandbox-pool/templates/login.html
new file mode 100644
index 0000000..f01b3d1
--- /dev/null
+++ b/warm-sandbox-pool/templates/login.html
@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Warm Sandbox Pool - Sign in</title>
+    <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
+</head>
+<body>
+    <div class="container">
+        <header>
+            <h1>🔥 Warm Sandbox Pool</h1>
+            <p class="subtitle">Pre-initialized OpenHands sandboxes with Ruby services ready to go</p>
+        </header>
+
+        <div class="panel login-panel">
+            <h2>🔒 Enter the access code</h2>
+            <p>
+                The pool controller printed an access code in its terminal output when it
+                started. If an OpenHands agent started it for you, the agent will have
+                given you the code along with this link.
+            </p>
+            <form id="login-form" class="login-form">
+                <input id="code-input" type="text" placeholder="XXXXX-XXXXX"
+                       autocomplete="off" autocapitalize="characters" spellcheck="false"
+                       autofocus>
+                <button type="submit" class="btn-primary">Unlock</button>
+            </form>
+            <p id="login-error" class="error-message" style="display: none;"></p>
+        </div>
+    </div>
+
+    <script src="{{ url_for('static', filename='login.js') }}"></script>
+</body>
+</html>
diff --git a/warm-sandbox-pool/test_structure.py b/warm-sandbox-pool/test_structure.py
index 42eafc1..bb6196f 100644
--- a/warm-sandbox-pool/test_structure.py
+++ b/warm-sandbox-pool/test_structure.py
@@ -23,6 +23,8 @@ def check_structure():
         "static/app.js",
         "static/styles.css",
         "templates/index.html",
+        "templates/login.html",
+        "static/login.js",
     ]
 
     missing = []

From 154dc5d5a8fcb574b5805d9bba41eb6e90bf6125 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 7 Oct 2026 19:54:45 +0000
Subject: [PATCH 8/9] warm-sandbox-pool: OpenHands styling, default port 12000,
 default pool size in the agent steps

Styling
- Restyle the UI with the OpenHands Agent Canvas "DeepSea" dark theme tokens
  (cool-grey scale on #0B0E14, warm gold primary with dark button text, the
  host's success and danger colors), flat 1px borders, no gradients or lift
  animations. Header uses the OpenHands logo and favicon from OpenHands/OpenHands.
- Status badges, info/result boxes and inputs use translucent tints so they
  stay readable on the dark surfaces.

Port
- Default PORT is now 12000, the first port an OpenHands sandbox publishes as a
  work URL, so running from a sandbox needs only HOST=0.0.0.0 and local runs
  use the same number.

Agent instructions
- The sandbox steps now say to use the default pool settings (pool of 3,
  threshold 2). The earlier advice to try POOL_SIZE=1 POOL_THRESHOLD=1 first
  leaves nothing to watch, because a refill only starts once ready drops below
  the threshold; removed from README and QUICKSTART.

Verified on beta through a work URL with the exact documented command
(HOST=0.0.0.0, defaults): sign-in, dashboard, two claims, refill and the
activity feed all render correctly in the new theme.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/QUICKSTART.md             |  17 +-
 warm-sandbox-pool/README.md                 |  29 ++--
 warm-sandbox-pool/pool_controller.py        |   7 +-
 warm-sandbox-pool/static/app.js             |   4 +-
 warm-sandbox-pool/static/favicon.svg        |   1 +
 warm-sandbox-pool/static/openhands-logo.svg |   9 ++
 warm-sandbox-pool/static/styles.css         | 168 ++++++++++++--------
 warm-sandbox-pool/templates/index.html      |   8 +-
 warm-sandbox-pool/templates/login.html      |   8 +-
 warm-sandbox-pool/test_structure.py         |   2 +
 10 files changed, 157 insertions(+), 96 deletions(-)
 create mode 100644 warm-sandbox-pool/static/favicon.svg
 create mode 100644 warm-sandbox-pool/static/openhands-logo.svg

diff --git a/warm-sandbox-pool/QUICKSTART.md b/warm-sandbox-pool/QUICKSTART.md
index 4ad428f..72ba80c 100644
--- a/warm-sandbox-pool/QUICKSTART.md
+++ b/warm-sandbox-pool/QUICKSTART.md
@@ -25,14 +25,15 @@ uv pip install -e .
 ## Run the Demo
 
 > **Running this from an OpenHands sandbox?** Start the controller with
-> `HOST=0.0.0.0 PORT=12000` and open the sandbox's `work-1-…` URL to watch the web UI
+> `HOST=0.0.0.0` (the default port, 12000, is published as the `work-1-…` URL) with the
+> default pool settings, and open that URL to watch the web UI
 > from your browser. Read the `ACCESS CODE:` line from the controller's output and give
 > it to the user to paste into the page. See "Run It From an OpenHands Sandbox" in
 > `README.md`, including its security note.
 
 > **This creates real sandboxes.** The controller starts `POOL_SIZE` (default 3)
-> sandboxes right away and keeps refilling the pool. For a first try use
-> `POOL_SIZE=1 POOL_THRESHOLD=1`. Press Ctrl-C to stop: unused pool sandboxes are
+> sandboxes right away and keeps refilling the pool. Keep the defaults (pool of 3,
+> threshold 2) so there is something to watch. Press Ctrl-C to stop: unused pool sandboxes are
 > deleted, sandboxes already attached to a conversation are left running.
 
 ```bash
@@ -46,14 +47,14 @@ python pool_controller.py
 # INFO pool_controller: Pool controller initialized: size=3, threshold=2
 # INFO pool_controller: Initial pool fill to 3 sandboxes
 # INFO pool_controller: Pool manager thread started
-# INFO pool_controller: Starting web server on 127.0.0.1:5000
-# INFO pool_controller: Open http://localhost:5000 in your browser
+# INFO pool_controller: Starting web server on 127.0.0.1:12000
+# INFO pool_controller: Open http://localhost:12000 in your browser
 # INFO pool_controller: ACCESS CODE: XXXXX-XXXXX  (paste it into the web page to sign in)
 ```
 
 ## Use the Demo (2-3 minutes)
 
-1. **Open http://localhost:5000** in your browser and paste the access code from the
+1. **Open http://localhost:12000** in your browser and paste the access code from the
    controller's output (the `ACCESS CODE:` line) into the sign-in page
 
 2. **Watch the pool initialize**:
@@ -135,7 +136,7 @@ Customize via environment variables:
 # Basic config
 export OH_API_KEY=your_key
 export OH_API_BASE=https://app.all-hands.dev  # or your instance
-export PORT=5000                               # Web UI port
+export PORT=12000                              # Web UI port
 export HOST=127.0.0.1                          # 0.0.0.0 only for a sandbox work URL
 
 # Pool sizing
@@ -181,7 +182,7 @@ PORT=8080 python pool_controller.py
 ┌─────────────────┐
 │  Browser (You)  │
 └────────┬────────┘
-         │ http://localhost:5000
+         │ http://localhost:12000
          ▼
 ┌─────────────────────────┐
 │ Flask Web Server        │
diff --git a/warm-sandbox-pool/README.md b/warm-sandbox-pool/README.md
index 7886d74..b425639 100644
--- a/warm-sandbox-pool/README.md
+++ b/warm-sandbox-pool/README.md
@@ -90,14 +90,15 @@ export OH_API_KEY=your_api_key_here
 python pool_controller.py
 ```
 
-Then open http://localhost:5000 in your browser. The controller prints a random
+Then open http://localhost:12000 in your browser. The controller prints a random
 **access code** when it starts (look for `ACCESS CODE:` in its output). Paste it into
 the page to sign in. Nothing is served without it, and a restart issues a new code.
 
 > **Heads up: this creates real sandboxes.** The controller immediately starts
 > `POOL_SIZE` sandboxes (default 3) and keeps topping the pool up as you use them.
-> Try it with `POOL_SIZE=1 POOL_THRESHOLD=1` first. Press Ctrl-C (or send SIGTERM)
-> to stop: every sandbox still sitting in the pool is deleted. Sandboxes already
+> Keep the defaults (pool of 3, threshold 2): a smaller pool leaves nothing to watch,
+> because the refill only starts once ready drops below the threshold. Press Ctrl-C
+> (or send SIGTERM) to stop: every sandbox still sitting in the pool is deleted. Sandboxes already
 > attached to a conversation are left running, like any other conversation sandbox.
 > If the controller is killed with SIGKILL it cannot clean up, so check your sandbox
 > list afterwards.
@@ -111,16 +112,17 @@ controller on one of those ports, binds it to all interfaces, and gives you the
 
 Steps for the agent (or for you, in a sandbox terminal):
 
-1. Pick a published port. The sandbox's environment lists its work URLs, for example
-   `https://work-1-<id>-runtime.<domain>/` for port 12000 and
-   `https://work-2-<id>-runtime.<domain>/` for port 12001.
-2. Start the controller on that port, bound to `0.0.0.0` (the default `127.0.0.1` is
-   not reachable through the work URL):
+1. Check which port the sandbox publishes. The controller's default, 12000, is the
+   first one: its work URL is `https://work-1-<id>-runtime.<domain>/`. Port 12001 is
+   `https://work-2-<id>-runtime.<domain>/`. If your environment lists different ports,
+   set `PORT` to one of them.
+2. Start the controller with the **default pool settings** (pool of 3, threshold 2;
+   do not lower them, or there is little to watch), bound to `0.0.0.0` because the
+   default `127.0.0.1` is not reachable through the work URL:
 
    ```bash
    export OH_API_KEY=your_api_key_here
-   OH_API_BASE=https://app.all-hands.dev POOL_SIZE=3 HOST=0.0.0.0 PORT=12000 \
-     python pool_controller.py
+   HOST=0.0.0.0 python pool_controller.py
    ```
 
 3. Read the access code from the controller's output (the line starting
@@ -151,8 +153,8 @@ starting a conversation all work through the proxy.
 > - Give the code only to the person who should have it. It is printed in the
 >   controller's output, so do not paste that output into public places.
 > - Run it briefly and stop it when you are done. Do not leave it running.
-> - Keep `POOL_SIZE` small (the default of 3 is fine). Each claim can trigger a refill,
->   so the total number of sandboxes grows by one per conversation started.
+> - Keep the default `POOL_SIZE` of 3. Each claim can trigger a refill, so the total
+>   number of sandboxes grows by one per conversation started.
 > - This is a demo gate, not a production login: there are no user accounts and no
 >   rate limiting on guesses. For anything longer-lived, put real authentication in
 >   front of it.
@@ -203,7 +205,8 @@ Environment variables:
   it through an OpenHands sandbox work URL. The UI can start conversations with your
   API key, so it is gated by the access code the controller prints at startup; see
   the security note above.
-- `PORT`: Web server port (default: `5000`)
+- `PORT`: Web server port (default: `12000`, one of the ports an OpenHands sandbox
+  publishes as a work URL)
 
 ### Testing the Ruby Service
 
diff --git a/warm-sandbox-pool/pool_controller.py b/warm-sandbox-pool/pool_controller.py
index 4f4bbe9..f39c3e1 100755
--- a/warm-sandbox-pool/pool_controller.py
+++ b/warm-sandbox-pool/pool_controller.py
@@ -10,7 +10,7 @@
     export OH_API_KEY=your_key_here
     python pool_controller.py
 
-Then open http://localhost:5000 in your browser. The controller prints a random
+Then open http://localhost:12000 in your browser. The controller prints a random
 access code when it starts; paste it into the web page to sign in. Nothing is served
 without it.
 
@@ -696,8 +696,9 @@ def parse_args():
     p.add_argument(
         "--port",
         type=int,
-        default=int(os.environ.get("PORT", "5000")),
-        help="Web server port (env: PORT, default: 5000)",
+        default=int(os.environ.get("PORT", "12000")),
+        help="Web server port (env: PORT, default: 12000, one of the ports an "
+        "OpenHands sandbox publishes as a work URL)",
     )
     p.add_argument(
         "--host",
diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
index f87331e..c570321 100644
--- a/warm-sandbox-pool/static/app.js
+++ b/warm-sandbox-pool/static/app.js
@@ -151,7 +151,7 @@ class PoolUI {
         const container = document.getElementById('sandbox-list');
 
         if (sandboxes.length === 0) {
-            container.innerHTML = '<p style="text-align: center; color: #6b7280;">No sandboxes yet...</p>';
+            container.innerHTML = '<p style="text-align: center; color: var(--text-secondary);">No sandboxes yet...</p>';
             return;
         }
 
@@ -308,7 +308,7 @@ class PoolUI {
                 <a href="${this.escapeHtml(data.conversation_url)}" target="_blank">
                     🔗 Open Conversation in OpenHands
                 </a>
-                <p style="margin-top: 16px; font-size: 0.875rem; color: #6b7280;">
+                <p style="margin-top: 16px; font-size: 0.875rem; color: var(--text-secondary);">
                     The pool refills automatically once its ready sandboxes drop below
                     the threshold. Watch the activity feed below.
                 </p>
diff --git a/warm-sandbox-pool/static/favicon.svg b/warm-sandbox-pool/static/favicon.svg
new file mode 100644
index 0000000..4877e59
--- /dev/null
+++ b/warm-sandbox-pool/static/favicon.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?> <svg id="App_Icon_Shape" data-name="App Icon Shape" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1024 1024"> <defs> <style> .cls-1 { fill: url(#linear-gradient); } .cls-2 { fill: #fff; } </style> <linearGradient id="linear-gradient" x1="512" y1="464.77" x2="512" y2="-1109.83" gradientUnits="userSpaceOnUse"> <stop offset="0" stop-color="#000"/> <stop offset="1" stop-color="#fff"/> </linearGradient> </defs> <path class="cls-1" d="M1024,651c0,14.24,0,28.48-.08,42.73-.07,12-.21,23.99-.53,35.98-.71,26.13-2.25,52.49-6.89,78.34-4.71,26.22-12.4,50.62-24.53,74.44-11.92,23.41-27.49,44.84-46.07,63.41-18.58,18.58-40,34.15-63.41,46.07-23.82,12.12-48.22,19.82-74.44,24.53-25.84,4.65-52.2,6.18-78.34,6.89-11.99.33-23.99.46-35.98.53-14.24.09-28.48.08-42.73.08h-278c-14.24,0-28.48,0-42.73-.08-12-.07-23.99-.21-35.98-.53-26.13-.71-52.49-2.25-78.34-6.89-26.22-4.71-50.62-12.4-74.44-24.53-23.41-11.92-44.84-27.49-63.41-46.07-18.58-18.58-34.15-40-46.07-63.41-12.12-23.82-19.82-48.22-24.53-74.44-4.65-25.84-6.18-52.2-6.89-78.34-.33-11.99-.46-23.99-.53-35.98C0,679.48,0,665.24,0,651v-278C0,358.76,0,344.52.08,330.27c.07-12,.21-23.99.53-35.98.71-26.13,2.25-52.49,6.89-78.34,4.71-26.22,12.4-50.62,24.53-74.44,11.92-23.41,27.49-44.84,46.07-63.41,18.58-18.58,40-34.15,63.41-46.07,23.82-12.12,48.22-19.82,74.44-24.53,25.84-4.65,52.2-6.18,78.34-6.89,11.99-.33,23.99-.46,35.98-.53C344.52,0,358.76,0,373,0h278c14.24,0,28.48,0,42.73.08,12,.07,23.99.21,35.98.53,26.13.71,52.49,2.25,78.34,6.89,26.22,4.71,50.62,12.4,74.44,24.53,23.41,11.92,44.84,27.49,63.41,46.07,18.58,18.58,34.15,40,46.07,63.41,12.12,23.82,19.82,48.22,24.53,74.44,4.65,25.84,6.18,52.2,6.89,78.34.33,11.99.46,23.99.53,35.98.09,14.24.08,28.48.08,42.73v278Z"/> <g> <path class="cls-2" d="M500.73,326.03v-73.61c0-6.1,4.95-11.04,11.04-11.04s11.04,4.94,11.04,11.04v73.61c0,6.1-4.94,11.04-11.04,11.04s-11.04-4.94-11.04-11.04Z"/> <path class="cls-2" d="M557.82,337l36.8-63.75c3.05-5.28,9.8-7.09,15.08-4.04,5.28,3.05,7.09,9.8,4.04,15.08l-36.8,63.75c-3.05,5.28-9.8,7.09-15.08,4.04-5.28-3.05-7.09-9.8-4.04-15.08Z"/> <path class="cls-2" d="M465.72,337l-36.8-63.75c-3.05-5.28-9.8-7.09-15.08-4.04-5.28,3.05-7.09,9.8-4.04,15.08l36.8,63.75c3.05,5.28,9.8,7.09,15.08,4.04,5.28-3.05,7.09-9.8,4.04-15.08Z"/> <path class="cls-2" d="M865.63,565.4c0-19.19,5.18-76.08,6.8-94.85,1.1-12.69-.43-19.65-2.47-23.2-1.5-2.61-3.84-4.45-9.49-4.83-4.08-.27-8.52.89-11.83,3.88-3.11,2.8-6.58,8.44-6.58,19.83l-.02.64-5.07,86.49c-.18,3.11-1.67,6.01-4.1,7.96-2.43,1.95-5.56,2.79-8.64,2.3l-53.15-8.41-57.32-7.61c-5.29-.7-9.33-5.1-9.57-10.43l-3.16-68.35-.03-.58c-1.41-27.21-2.75-52.04-2.75-59.72,0-21.42-3.63-30.46-6.79-34.26-2.53-3.03-6.16-4.36-13.94-4.36-2.79,0-4.76.57-6.24,1.44-1.45.85-3.11,2.37-4.69,5.35-3.39,6.39-5.85,18.39-4.93,39.36,1.19,27.2,3.04,47.52,4.86,65.84,1.81,18.29,3.62,34.9,4.63,54.19,1.57,30.21,1.43,51.03.2,65.16-.62,7.06-1.53,12.76-2.77,17.27-1.17,4.27-2.93,8.62-5.97,11.86-3.69,3.93-8.95,5.81-14.41,4.49-4.33-1.04-7.38-3.79-9.04-5.54-3.48-3.66-5.94-8.38-6.9-10.81-5.61-14.15-22.96-47.01-46.46-65.56-6.85-5.41-11.85-6.97-14.99-7.21-2.96-.22-5.11.65-6.8,1.99-1.86,1.48-3.25,3.63-3.94,5.66-.24.72-.35,1.23-.39,1.56,6.37,10.75,31.63,50.16,43.54,90.15,8.88,29.81,30.28,60.19,46.27,73.2,15.48,12.6,43.29,20.41,74.62,21.95,31.04,1.52,63-3.23,85.5-13.32,43.46-19.48,52.31-62.38,56.27-80.98,3.08-14.43,3.14-29.84,2.31-44.14-.41-7.13-1.02-13.8-1.56-19.95-.52-5.97-.99-11.74-.99-16.47ZM761.65,380.26c0-6.7-1.79-12.67-4.75-16.66-2.68-3.61-6.62-6.11-12.95-6.11-5.18,0-8.67.64-11.13,1.69-2.2.94-4.05,2.4-5.74,5.12-3.88,6.27-6.74,18.88-6.75,43.99l2.75,59.45c1.03,19.83,2.1,41.32,2.8,59.19l35.77,4.75v-151.42ZM783.73,534.86l31.9,5.05,4.35-73.94v-57.02c0-7.83-3.19-12.62-6.96-15.68-4.21-3.42-9.12-4.64-11.44-4.64-4.22,0-8.59.66-11.73,2.89-2.42,1.72-6.11,5.78-6.11,17.44v125.91ZM842.06,424.42c6.61-3.29,13.68-4.34,19.89-3.93,11.26.75,21.19,5.47,27.16,15.85,5.42,9.44,6.55,21.92,5.32,36.12-1.7,19.62-6.73,75.01-6.73,92.94,0,3.6.38,8.39.91,14.56.52,6,1.17,13.05,1.61,20.59.87,15.04.93,32.74-2.76,50.02-3.84,18-14.24,72.04-68.84,96.52-26.54,11.89-62.2,16.87-95.62,15.23-33.13-1.63-66.61-9.88-87.49-26.88-19.65-16-43.43-50.25-53.49-84.02-11.36-38.14-35.96-75.76-42.1-86.42-3.62-6.28-2.48-13.73-.8-18.7,1.9-5.6,5.58-11.46,11.12-15.86,5.71-4.53,13.28-7.4,22.2-6.73,8.74.66,17.8,4.64,27.01,11.9,23.69,18.71,41.08,48.22,49.6,66.31.09-.83.19-1.7.27-2.61,1.11-12.65,1.3-32.3-.25-62.1-.97-18.65-2.71-34.62-4.55-53.16-1.84-18.51-3.74-39.28-4.95-67.06-.97-22.16,1.3-39,7.48-50.66,3.2-6.05,7.54-10.86,13.05-14.08,5.49-3.21,11.47-4.45,17.38-4.45,8.74,0,19.63,1.23,28.29,9.51.77-1.64,1.6-3.19,2.51-4.65,4-6.47,9.33-11.03,15.85-13.81,6.27-2.67,13.07-3.46,19.79-3.46,13.51,0,23.95,5.96,30.68,15.04,4.36,5.87,6.97,12.77,8.21,19.77,7.17-3.24,14.34-3.66,18.73-3.66,7.49,0,17.3,3.03,25.36,9.59,8.5,6.9,15.13,17.8,15.13,32.82v15.47Z"/> <path class="cls-2" d="M158.37,565.4c0-19.19-5.18-76.08-6.8-94.85-1.1-12.69.43-19.65,2.47-23.2,1.5-2.61,3.84-4.45,9.48-4.83,4.08-.27,8.52.89,11.84,3.88,3.11,2.8,6.58,8.44,6.58,19.83l.02.64,5.07,86.49c.18,3.11,1.67,6.01,4.1,7.96,2.43,1.95,5.57,2.79,8.65,2.3l53.15-8.41,57.32-7.61c5.3-.7,9.33-5.1,9.57-10.43l3.16-68.35.03-.58c1.41-27.21,2.74-52.04,2.74-59.72,0-21.42,3.63-30.46,6.8-34.26,2.53-3.03,6.16-4.36,13.94-4.36,2.79,0,4.76.57,6.24,1.44,1.45.85,3.11,2.37,4.69,5.35,3.38,6.39,5.85,18.39,4.93,39.36-1.19,27.2-3.04,47.52-4.86,65.84-1.81,18.29-3.62,34.9-4.63,54.19-1.57,30.21-1.43,51.03-.2,65.16.62,7.06,1.53,12.76,2.76,17.27,1.17,4.27,2.92,8.62,5.97,11.86,3.69,3.93,8.95,5.81,14.41,4.49,4.33-1.04,7.38-3.79,9.04-5.54,3.48-3.66,5.94-8.38,6.9-10.81,5.61-14.15,22.96-47.01,46.46-65.56,6.85-5.41,11.85-6.97,14.99-7.21,2.96-.22,5.11.65,6.8,1.99,1.86,1.48,3.25,3.63,3.94,5.66.24.72.35,1.23.39,1.56-6.37,10.75-31.63,50.16-43.54,90.15-8.88,29.81-30.28,60.19-46.27,73.2-15.48,12.6-43.29,20.41-74.62,21.95-31.03,1.52-63-3.23-85.5-13.32-43.46-19.48-52.31-62.38-56.28-80.98-3.08-14.43-3.14-29.84-2.31-44.14.41-7.13,1.02-13.8,1.56-19.95.52-5.97.99-11.74.99-16.47ZM262.35,380.26c0-6.7,1.79-12.67,4.75-16.66,2.68-3.61,6.62-6.11,12.95-6.11,5.18,0,8.67.64,11.13,1.69,2.21.94,4.06,2.4,5.74,5.12,3.89,6.27,6.74,18.88,6.75,43.99l-2.75,59.45c-1.03,19.83-2.1,41.32-2.8,59.19l-35.77,4.75v-151.42ZM240.27,534.86l-31.9,5.05-4.35-73.94v-57.02c0-7.83,3.19-12.62,6.97-15.68,4.21-3.42,9.12-4.64,11.44-4.64,4.23,0,8.59.66,11.73,2.89,2.42,1.72,6.11,5.78,6.11,17.44v125.91ZM181.94,424.42c-6.61-3.29-13.68-4.34-19.89-3.93-11.26.75-21.19,5.47-27.16,15.85-5.42,9.44-6.55,21.92-5.32,36.12,1.7,19.62,6.73,75.01,6.73,92.94,0,3.6-.37,8.39-.91,14.56-.52,6-1.17,13.05-1.61,20.59-.87,15.04-.93,32.74,2.76,50.02,3.84,18,14.23,72.04,68.84,96.52,26.53,11.89,62.2,16.87,95.62,15.23,33.13-1.63,66.61-9.88,87.48-26.88,19.65-16,43.43-50.25,53.49-84.02,11.36-38.14,35.96-75.76,42.1-86.42,3.62-6.28,2.48-13.73.8-18.7-1.9-5.6-5.58-11.46-11.12-15.86-5.71-4.53-13.28-7.4-22.2-6.73-8.74.66-17.8,4.64-27.01,11.9-23.69,18.71-41.08,48.22-49.6,66.31-.09-.83-.19-1.7-.27-2.61-1.11-12.65-1.3-32.3.25-62.1.97-18.65,2.71-34.62,4.55-53.16,1.83-18.51,3.73-39.28,4.95-67.06.97-22.16-1.31-39-7.48-50.66-3.2-6.05-7.54-10.86-13.05-14.08-5.49-3.21-11.47-4.45-17.38-4.45-8.74,0-19.62,1.23-28.29,9.51-.76-1.64-1.6-3.19-2.5-4.65-4-6.47-9.33-11.03-15.85-13.81-6.27-2.67-13.07-3.46-19.79-3.46-13.51,0-23.95,5.96-30.68,15.04-4.36,5.87-6.97,12.77-8.22,19.77-7.17-3.24-14.34-3.66-18.73-3.66-7.49,0-17.3,3.03-25.36,9.59-8.5,6.9-15.13,17.8-15.13,32.82v15.47Z"/> </g> </svg>
diff --git a/warm-sandbox-pool/static/openhands-logo.svg b/warm-sandbox-pool/static/openhands-logo.svg
new file mode 100644
index 0000000..f6938f7
--- /dev/null
+++ b/warm-sandbox-pool/static/openhands-logo.svg
@@ -0,0 +1,9 @@
+<svg width="47" height="30" viewBox="0 0 148 100" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M71.754 16.863V2.97414C71.754 1.82355 72.6871 0.890503 73.8377 0.890503C74.9883 0.890503 75.9213 1.82355 75.9213 2.97414V16.863C75.9213 18.0136 74.9883 18.9466 73.8377 18.9466C72.6871 18.9466 71.754 18.0136 71.754 16.863Z" fill="white"/>
+<path d="M82.5273 18.9329L89.4717 6.90477C90.047 5.90832 91.3215 5.5668 92.318 6.1421C93.3144 6.7174 93.6559 7.99197 93.0806 8.98841L86.1362 21.0165C85.5609 22.0129 84.2864 22.3545 83.2899 21.7792C82.2935 21.2039 81.952 19.9293 82.5273 18.9329Z" fill="white"/>
+<path d="M65.1481 18.9329L58.2037 6.90477C57.6284 5.90832 56.3538 5.5668 55.3574 6.1421C54.3609 6.7174 54.0194 7.99197 54.5947 8.98841L61.5391 21.0165C62.1144 22.0129 63.389 22.3545 64.3854 21.7792C65.3819 21.2039 65.7234 19.9293 65.1481 18.9329Z" fill="white"/>
+<path d="M98.5045 92.4969C95.1427 89.7602 90.8793 83.6628 89.0929 77.664C86.8598 70.1655 82.0309 62.777 80.9578 60.9138C80.0056 59.2602 83.0313 53.2605 89.0929 58.0459C93.9421 61.8742 97.3878 68.466 98.5045 71.2833C98.9566 72.4239 103.006 79.2475 101.827 56.6051C101.455 49.445 100.49 44.3126 100.036 33.9388C99.6807 25.7997 101.824 23.057 105.11 23.057C108.396 23.057 111.106 24.1244 111.106 32.4283C111.106 22.8682 113.154 20.7141 117.646 20.7147C121.39 20.7153 123.069 23.9077 123.069 27.0952V32.5084C123.069 27.0952 126.669 26.5896 128.519 26.5896C130.37 26.5896 134.076 28.1957 134.076 32.5084V43.317C134.076 38.116 137.324 36.601 139.773 36.765C142.963 36.9786 144.405 39.2382 143.965 44.3126C143.651 47.9349 142.689 58.5273 142.689 62.0291C142.689 65.1712 143.965 71.6801 142.689 77.664C141.953 81.1168 140.137 90.2628 130.885 94.4102C121.634 98.5575 105.364 98.0807 98.5045 92.4969Z" fill="transparent"/>
+<path d="M140.606 62.0292C140.606 58.409 141.583 47.6748 141.89 44.1323C142.097 41.7374 141.809 40.4247 141.424 39.7542C141.141 39.2626 140.699 38.915 139.634 38.8436C138.865 38.7921 138.027 39.0114 137.401 39.5761C136.814 40.1052 136.159 41.1682 136.159 43.3176L136.155 43.4388L135.198 59.758C135.164 60.3451 134.883 60.8911 134.424 61.2599C133.966 61.6284 133.374 61.7859 132.793 61.6941L122.764 60.1068L111.948 58.6703C110.949 58.5376 110.188 57.7084 110.142 56.7016L109.545 43.8055L109.54 43.6959C109.274 38.5609 109.022 33.8767 109.022 32.4282C109.022 28.3859 108.338 26.6806 107.74 25.9634C107.263 25.3915 106.577 25.1402 105.11 25.1402C104.583 25.1402 104.212 25.2481 103.933 25.4111C103.659 25.5714 103.346 25.8587 103.049 26.4208C102.41 27.6257 101.945 29.891 102.118 33.8479C102.342 38.9804 102.692 42.8146 103.035 46.2718C103.377 49.7231 103.718 52.8561 103.908 56.4971C104.204 62.1966 104.178 66.1256 103.945 68.7924C103.828 70.124 103.656 71.1996 103.423 72.0501C103.202 72.8558 102.871 73.6757 102.296 74.2887C101.6 75.0303 100.608 75.3844 99.577 75.136C98.7592 74.9389 98.1847 74.4215 97.8706 74.0916C97.2141 73.4017 96.7501 72.5106 96.568 72.0512C95.5097 69.3812 92.2352 63.1808 87.8023 59.6811C86.5089 58.6599 85.5666 58.3652 84.9736 58.3204C84.4148 58.2783 84.0094 58.4436 83.6909 58.6967C83.34 58.9756 83.0781 59.3811 82.9479 59.7643C82.9019 59.8999 82.8823 59.9968 82.8741 60.0584C84.0759 62.0865 88.8421 69.5222 91.0896 77.069C92.7648 82.6941 96.8038 88.4259 99.8194 90.8809C102.74 93.258 107.988 94.7313 113.9 95.0218C119.756 95.3095 125.788 94.4121 130.033 92.5092C138.233 88.8334 139.903 80.7382 140.651 77.2292C141.232 74.5057 141.243 71.5987 141.087 68.9009C141.01 67.5551 140.894 66.2969 140.793 65.1373C140.695 64.0105 140.606 62.9215 140.606 62.0292ZM120.986 27.0953C120.986 25.8314 120.648 24.7049 120.089 23.9514C119.583 23.27 118.84 22.7987 117.646 22.7984C116.668 22.7982 116.011 22.9187 115.546 23.1167C115.13 23.2943 114.781 23.5699 114.463 24.0831C113.73 25.2671 113.192 27.6455 113.189 32.384L113.707 43.6021C113.901 47.3443 114.103 51.3994 114.236 54.7707L120.986 55.6666V27.0953ZM125.153 56.2652L131.172 57.218L131.992 43.267V32.5083C131.992 31.031 131.39 30.1275 130.678 29.5489C129.884 28.9039 128.957 28.6731 128.519 28.6731C127.722 28.6731 126.899 28.797 126.306 29.2179C125.849 29.5421 125.153 30.3087 125.153 32.5083V56.2652ZM136.159 35.4278C137.406 34.8069 138.74 34.6083 139.912 34.6868C142.037 34.8292 143.91 35.718 145.037 37.6779C146.06 39.4592 146.273 41.8136 146.041 44.4927C145.72 48.1949 144.772 58.6457 144.772 62.0292C144.772 62.708 144.843 63.6116 144.944 64.7758C145.042 65.907 145.165 67.2389 145.247 68.6606C145.411 71.4987 145.422 74.8383 144.727 78.0987C144.002 81.4953 142.041 91.6918 131.738 96.3108C126.731 98.5551 120.002 99.4936 113.696 99.1838C107.445 98.8767 101.128 97.3189 97.1887 94.1122C93.4809 91.0936 88.9938 84.6307 87.0962 78.2589C84.9529 71.0619 80.3109 63.9646 79.1527 61.9533C78.4706 60.7689 78.684 59.3628 79.0019 58.4258C79.3607 57.3688 80.0554 56.2631 81.0993 55.4337C82.1758 54.5784 83.6043 54.0377 85.2876 54.1647C86.9369 54.2893 88.6462 55.0393 90.3834 56.4107C94.8541 59.9401 98.1342 65.5082 99.7424 68.9231C99.759 68.7664 99.779 68.6024 99.7941 68.4298C100.003 66.0435 100.039 62.3344 99.7467 56.7132C99.5635 53.1942 99.2356 50.1809 98.8888 46.6828C98.5425 43.1904 98.184 39.2713 97.955 34.0302C97.7722 29.8481 98.2012 26.6722 99.3672 24.471C99.9716 23.3302 100.79 22.4223 101.83 21.814C102.866 21.2087 103.995 20.974 105.11 20.974C106.759 20.974 108.813 21.2062 110.448 22.7678C110.593 22.4576 110.75 22.1652 110.921 21.8899C111.676 20.6698 112.681 19.8084 113.912 19.2835C115.095 18.7791 116.378 18.6309 117.646 18.6311C120.195 18.6315 122.165 19.7565 123.435 21.4683C124.257 22.576 124.75 23.8776 124.985 25.1982C126.338 24.5876 127.691 24.5068 128.519 24.5068C129.933 24.5068 131.784 25.0791 133.305 26.3154C134.908 27.6179 136.159 29.6733 136.159 32.5083V35.4278Z" fill="white"/>
+<path d="M49.258 92.4969C52.6198 89.7602 56.8832 83.6628 58.6696 77.664C60.9027 70.1655 65.7316 62.777 66.8047 60.9138C67.757 59.2602 64.7312 53.2605 58.6696 58.0459C53.8204 61.8742 50.3747 68.466 49.258 71.2833C48.8059 72.4239 44.7566 79.2475 45.935 56.6051C46.3077 49.445 47.2728 44.3126 47.7261 33.9388C48.0818 25.7997 45.9381 23.057 42.6523 23.057C39.3666 23.057 36.6568 24.1244 36.6568 32.4283C36.6568 22.8682 34.6087 20.7141 30.1168 20.7147C26.3728 20.7153 24.6934 23.9077 24.6934 27.0952V32.5084C24.6934 27.0952 21.0938 26.5896 19.243 26.5896C17.3923 26.5896 13.687 28.1957 13.687 32.5084V43.317C13.687 38.116 10.4388 36.601 7.98968 36.765C4.79943 36.9786 3.3574 39.2382 3.79721 44.3126C4.11115 47.9349 5.07331 58.5273 5.07331 62.0291C5.07331 65.1712 3.79721 71.6801 5.07331 77.664C5.80964 81.1168 7.62551 90.2628 16.8772 94.4102C26.129 98.5575 42.3987 98.0807 49.258 92.4969Z" fill="transparent"/>
+<path d="M7.15667 62.0292C7.15667 58.409 6.18001 47.6748 5.87297 44.1323C5.66546 41.7374 5.95363 40.4247 6.33881 39.7542C6.62122 39.2626 7.06342 38.915 8.1284 38.8436C8.89765 38.7921 9.7355 39.0114 10.3617 39.5761C10.9484 40.1052 11.6032 41.1682 11.6032 43.3176L11.6075 43.4388L12.5644 59.758C12.5989 60.3451 12.8798 60.8911 13.338 61.2599C13.7961 61.6284 14.3888 61.7859 14.9695 61.6941L24.9988 60.1068L35.8144 58.6703C36.8136 58.5376 37.5741 57.7084 37.6208 56.7016L38.2174 43.8055L38.2226 43.6959C38.4887 38.5609 38.7401 33.8767 38.7401 32.4282C38.7401 28.3859 39.4246 26.6806 40.0228 25.9634C40.4997 25.3915 41.1851 25.1402 42.6523 25.1402C43.1795 25.1402 43.5506 25.2481 43.8296 25.4111C44.1038 25.5714 44.416 25.8587 44.7139 26.4208C45.3521 27.6257 45.8174 29.891 45.6445 33.8479C45.4202 38.9804 45.0703 42.8146 44.7276 46.2718C44.3854 49.7231 44.0444 52.8561 43.8549 56.4971C43.5583 62.1966 43.5848 66.1256 43.818 68.7924C43.9345 70.124 44.107 71.1996 44.3397 72.0501C44.5602 72.8558 44.891 73.6757 45.4664 74.2887C46.1626 75.0303 47.1547 75.3844 48.1855 75.136C49.0033 74.9389 49.5779 74.4215 49.8919 74.0916C50.5484 73.4017 51.0124 72.5106 51.1945 72.0512C52.2528 69.3812 55.5273 63.1808 59.9602 59.6811C61.2536 58.6599 62.1959 58.3652 62.7889 58.3204C63.3477 58.2783 63.7531 58.4436 64.0716 58.6967C64.4225 58.9756 64.6844 59.3811 64.8146 59.7643C64.8606 59.8999 64.8802 59.9968 64.8884 60.0584C63.6866 62.0865 58.9205 69.5222 56.6729 77.069C54.9978 82.6941 50.9587 88.4259 47.9431 90.8809C45.0229 93.258 39.7748 94.7313 33.8625 95.0218C28.0069 95.3095 21.9748 94.4121 17.7298 92.5092C9.52994 88.8334 7.85968 80.7382 7.11135 77.2292C6.5306 74.5057 6.51956 71.5987 6.67502 68.9009C6.75257 67.5551 6.86815 66.2969 6.96907 65.1373C7.06713 64.0105 7.15666 62.9215 7.15667 62.0292ZM26.7768 27.0953C26.7768 25.8314 27.1148 24.7049 27.6737 23.9514C28.1793 23.27 28.9221 22.7987 30.1168 22.7984C31.0942 22.7982 31.7519 22.9187 32.2162 23.1167C32.6327 23.2943 32.9818 23.5699 33.2997 24.0831C34.0329 25.2671 34.5706 27.6455 34.5739 32.384L34.0554 43.6021C33.8615 47.3443 33.6592 51.3994 33.5263 54.7707L26.7768 55.6666V27.0953ZM22.6096 56.2652L16.5905 57.218L15.7705 43.267V32.5083C15.7705 31.031 16.3726 30.1275 17.0848 29.5489C17.8786 28.9039 18.8059 28.6731 19.2433 28.6731C20.0405 28.6731 20.8635 28.797 21.4565 29.2179C21.9131 29.5421 22.6095 30.3087 22.6096 32.5083V56.2652ZM11.6032 35.4278C10.3568 34.8069 9.02271 34.6083 7.85016 34.6868C5.72547 34.8292 3.85203 35.718 2.7259 37.6779C1.70253 39.4592 1.4893 41.8136 1.7215 44.4927C2.04237 48.1949 2.99044 58.6457 2.99044 62.0292C2.99043 62.708 2.91997 63.6116 2.81865 64.7758C2.7202 65.907 2.59705 67.2389 2.51511 68.6606C2.35156 71.4987 2.34047 74.8383 3.03576 78.0987C3.76011 81.4953 5.7216 91.6918 16.0245 96.3108C21.0312 98.5551 27.7601 99.4936 34.0669 99.1838C40.3173 98.8767 46.6346 97.3189 50.5738 94.1122C54.2816 91.0936 58.7687 84.6307 60.6663 78.2589C62.8096 71.0619 67.4516 63.9646 68.6099 61.9533C69.292 60.7689 69.0785 59.3628 68.7606 58.4258C68.4018 57.3688 67.7071 56.2631 66.6632 55.4337C65.5867 54.5784 64.1582 54.0377 62.4749 54.1647C60.8256 54.2893 59.1163 55.0393 57.3791 56.4107C52.9084 59.9401 49.6283 65.5082 48.0201 68.9231C48.0035 68.7664 47.9835 68.6024 47.9684 68.4298C47.7597 66.0435 47.7233 62.3344 48.0159 56.7132C48.199 53.1942 48.5269 50.1809 48.8738 46.6828C49.22 43.1904 49.5785 39.2713 49.8076 34.0302C49.9903 29.8481 49.5613 26.6722 48.3953 24.471C47.7909 23.3302 46.9729 22.4223 45.9322 21.814C44.8964 21.2087 43.7676 20.974 42.6523 20.974C41.0038 20.974 38.9498 21.2062 37.3141 22.7678C37.1699 22.4576 37.0125 22.1652 36.842 21.8899C36.0864 20.6698 35.0817 19.8084 33.8509 19.2835C32.668 18.7791 31.3849 18.6309 30.1168 18.6311C27.5676 18.6315 25.5976 19.7565 24.3275 21.4683C23.5057 22.576 23.0121 23.8776 22.7771 25.1982C21.4248 24.5876 20.0718 24.5068 19.2433 24.5068C17.8299 24.5068 15.9789 25.0791 14.4573 26.3154C12.8543 27.6179 11.6033 29.6733 11.6032 32.5083V35.4278Z" fill="white"/>
+</svg>
diff --git a/warm-sandbox-pool/static/styles.css b/warm-sandbox-pool/static/styles.css
index 754d461..f12c52e 100644
--- a/warm-sandbox-pool/static/styles.css
+++ b/warm-sandbox-pool/static/styles.css
@@ -1,18 +1,41 @@
-/* Warm Sandbox Pool - UI Styles */
+/* Warm Sandbox Pool - UI Styles
+   Tokens mirror the OpenHands Agent Canvas "DeepSea" dark theme
+   (OpenHands/OpenHands: src/themes, src/styles/agent-server-ui-style-scope.ts). */
 
 :root {
-    --primary-color: #2563eb;
-    --success-color: #10b981;
-    --warning-color: #f59e0b;
-    --danger-color: #ef4444;
-    --info-color: #3b82f6;
-    --bg-light: #f9fafb;
-    --bg-white: #ffffff;
-    --text-primary: #111827;
-    --text-secondary: #6b7280;
-    --border-color: #e5e7eb;
-    --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
-    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+    color-scheme: dark;
+
+    --cool-grey-50: #F7F9FC;
+    --cool-grey-100: #EEF2F7;
+    --cool-grey-300: #C3CDDC;
+    --cool-grey-400: #A3B0C4;
+    --cool-grey-500: #7E8A9E;
+    --cool-grey-700: #4B5468;
+    --cool-grey-800: #383F50;
+    --cool-grey-900: #2C313F;
+    --cool-grey-925: #21252F;
+    --cool-grey-950: #0B0E14;
+    --cool-grey-975: #05070A;
+
+    --oh-color-primary: #C9B974;
+    --oh-accent-foreground: var(--cool-grey-950);
+    --oh-success: #A5E75E;
+    --oh-danger: #E76A5E;
+
+    --primary-color: var(--oh-color-primary);
+    --success-color: var(--oh-success);
+    --warning-color: var(--oh-color-primary);
+    --danger-color: var(--oh-danger);
+    --info-color: var(--cool-grey-400);
+    --bg-light: var(--cool-grey-950);
+    --bg-white: var(--cool-grey-925);
+    --text-primary: var(--cool-grey-100);
+    --text-secondary: var(--cool-grey-400);
+    --border-color: var(--cool-grey-800);
+    --shadow: none;
+    --shadow-lg: none;
+
+    --font-mono: ui-monospace, 'SF Mono', Menlo, Monaco, Consolas, 'Courier New', monospace;
 }
 
 * {
@@ -22,7 +45,8 @@
 }
 
 body {
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif;
+    font-family: -apple-system, 'SF Pro', BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+    -webkit-font-smoothing: antialiased;
     background-color: var(--bg-light);
     color: var(--text-primary);
     line-height: 1.6;
@@ -35,23 +59,31 @@ body {
 }
 
 header {
-    text-align: center;
-    margin-bottom: 30px;
-    padding: 20px;
-    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-    color: white;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    margin-bottom: 20px;
+    padding: 16px 24px;
+    background: var(--bg-white);
+    border: 1px solid var(--border-color);
     border-radius: 12px;
-    box-shadow: var(--shadow-lg);
+}
+
+.brand-logo {
+    height: 30px;
+    width: auto;
 }
 
 header h1 {
-    font-size: 2.5rem;
-    margin-bottom: 8px;
+    font-size: 1.25rem;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    color: #ffffff;
 }
 
 header .subtitle {
-    font-size: 1.1rem;
-    opacity: 0.95;
+    font-size: 0.875rem;
+    color: var(--text-secondary);
 }
 
 .main-grid {
@@ -69,9 +101,9 @@ header .subtitle {
 
 .panel {
     background: var(--bg-white);
+    border: 1px solid var(--border-color);
     border-radius: 12px;
     padding: 24px;
-    box-shadow: var(--shadow);
 }
 
 .panel h2 {
@@ -152,9 +184,11 @@ header .subtitle {
 .login-form input {
     flex: 1;
     padding: 12px;
-    border: 2px solid var(--border-color);
+    border: 1px solid var(--cool-grey-700);
     border-radius: 8px;
-    font-family: 'Courier New', monospace;
+    background: var(--bg-light);
+    color: #ffffff;
+    font-family: var(--font-mono);
     font-size: 1.25rem;
     letter-spacing: 0.1em;
     text-transform: uppercase;
@@ -213,7 +247,7 @@ header .subtitle {
 .event-log {
     max-height: 320px;
     overflow-y: auto;
-    font-family: 'Courier New', monospace;
+    font-family: var(--font-mono);
     font-size: 0.8rem;
 }
 
@@ -249,7 +283,7 @@ header .subtitle {
     padding: 10px 12px;
     margin-bottom: 12px;
     border-radius: 8px;
-    background: #fef3c7;
+    background: color-mix(in srgb, var(--warning-color) 10%, transparent);
     font-size: 0.875rem;
 }
 
@@ -270,7 +304,7 @@ header .subtitle {
 
 .sandbox-card {
     padding: 16px;
-    border: 2px solid var(--border-color);
+    border: 1px solid var(--border-color);
     border-radius: 8px;
     background: var(--bg-white);
     transition: all 0.2s;
@@ -289,7 +323,7 @@ header .subtitle {
 }
 
 .sandbox-id {
-    font-family: 'Courier New', monospace;
+    font-family: var(--font-mono);
     font-size: 0.875rem;
     color: var(--text-secondary);
     flex: 1;
@@ -304,28 +338,28 @@ header .subtitle {
 }
 
 .status-starting {
-    background: #fee2e2;
-    color: #991b1b;
+    background: color-mix(in srgb, var(--danger-color) 16%, transparent);
+    color: var(--danger-color);
 }
 
 .status-preparing {
-    background: #fef3c7;
-    color: #92400e;
+    background: color-mix(in srgb, var(--warning-color) 16%, transparent);
+    color: var(--warning-color);
 }
 
 .status-ready {
-    background: #d1fae5;
-    color: #065f46;
+    background: color-mix(in srgb, var(--success-color) 16%, transparent);
+    color: var(--success-color);
 }
 
 .status-allocated {
-    background: #dbeafe;
-    color: #1e40af;
+    background: color-mix(in srgb, var(--info-color) 16%, transparent);
+    color: var(--cool-grey-300);
 }
 
 .status-failed {
-    background: #fecaca;
-    color: #7f1d1d;
+    background: color-mix(in srgb, var(--danger-color) 16%, transparent);
+    color: var(--danger-color);
 }
 
 .sandbox-details {
@@ -337,10 +371,10 @@ header .subtitle {
 .sandbox-log {
     margin-top: 8px;
     padding: 8px;
-    background: #f9fafb;
+    background: var(--bg-light);
     border-left: 3px solid var(--info-color);
     border-radius: 4px;
-    font-family: 'Courier New', monospace;
+    font-family: var(--font-mono);
     font-size: 0.75rem;
     max-height: 100px;
     overflow-y: auto;
@@ -425,7 +459,7 @@ header .subtitle {
 
 .info-box {
     padding: 16px;
-    background: #dbeafe;
+    background: color-mix(in srgb, var(--info-color) 10%, transparent);
     border-left: 4px solid var(--info-color);
     border-radius: 8px;
     margin-bottom: 20px;
@@ -448,24 +482,32 @@ header .subtitle {
 .conversation-form textarea {
     width: 100%;
     padding: 12px;
-    border: 2px solid var(--border-color);
+    border: 1px solid var(--cool-grey-700);
     border-radius: 8px;
+    background: var(--bg-light);
+    color: #ffffff;
     font-family: inherit;
     font-size: 1rem;
     resize: vertical;
     transition: border-color 0.2s;
 }
 
+.conversation-form textarea::placeholder,
+.login-form input::placeholder {
+    color: var(--cool-grey-500);
+}
+
 .conversation-form textarea:focus {
     outline: none;
-    border-color: var(--primary-color);
+    border-color: rgba(255, 255, 255, 0.4);
+    box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.2);
 }
 
 .btn-primary {
     width: 100%;
     padding: 14px 24px;
     background: var(--primary-color);
-    color: white;
+    color: var(--oh-accent-foreground);
     border: none;
     border-radius: 8px;
     font-size: 1rem;
@@ -476,32 +518,25 @@ header .subtitle {
 }
 
 .btn-primary:hover {
-    background: #1d4ed8;
-    transform: translateY(-2px);
-    box-shadow: var(--shadow-lg);
-}
-
-.btn-primary:active {
-    transform: translateY(0);
+    opacity: 0.8;
 }
 
 .btn-primary:disabled {
-    background: var(--text-secondary);
+    opacity: 0.3;
     cursor: not-allowed;
-    transform: none;
 }
 
 .result-area {
     margin-top: 20px;
     padding: 16px;
-    background: #d1fae5;
+    background: color-mix(in srgb, var(--success-color) 10%, transparent);
     border-left: 4px solid var(--success-color);
     border-radius: 8px;
     animation: fadeIn 0.5s;
 }
 
 .result-area.error {
-    background: #fee2e2;
+    background: color-mix(in srgb, var(--danger-color) 12%, transparent);
     border-left-color: var(--danger-color);
 }
 
@@ -517,8 +552,9 @@ header .subtitle {
     display: inline-block;
     margin-top: 12px;
     padding: 10px 20px;
-    background: white;
-    color: var(--primary-color);
+    background: var(--cool-grey-900);
+    border: 1px solid var(--cool-grey-700);
+    color: var(--cool-grey-100);
     text-decoration: none;
     border-radius: 6px;
     font-weight: 600;
@@ -527,15 +563,15 @@ header .subtitle {
 
 .result-area a:hover {
     background: var(--primary-color);
-    color: white;
-    transform: translateY(-2px);
+    border-color: var(--primary-color);
+    color: var(--oh-accent-foreground);
 }
 
 /* Info Section */
 .info-section {
     margin-top: 30px;
     padding-top: 20px;
-    border-top: 2px solid var(--border-color);
+    border-top: 1px solid var(--border-color);
 }
 
 .info-section h3 {
@@ -563,14 +599,14 @@ header .subtitle {
     background: var(--bg-light);
     padding: 2px 6px;
     border-radius: 4px;
-    font-family: 'Courier New', monospace;
+    font-family: var(--font-mono);
     font-size: 0.875rem;
 }
 
 .note {
     margin-top: 16px;
     padding: 12px;
-    background: #fef3c7;
+    background: color-mix(in srgb, var(--warning-color) 10%, transparent);
     border-left: 4px solid var(--warning-color);
     border-radius: 8px;
     font-size: 0.875rem;
@@ -596,7 +632,7 @@ footer a:hover {
 /* Error State */
 .error-message {
     color: var(--danger-color);
-    background: #fee2e2;
+    background: color-mix(in srgb, var(--danger-color) 12%, transparent);
     padding: 12px;
     border-radius: 8px;
     margin-top: 12px;
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index 3559eee..4cb62f1 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -4,13 +4,17 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Warm Sandbox Pool Demo</title>
+    <link rel="icon" type="image/svg+xml" href="{{ url_for('static', filename='favicon.svg') }}">
     <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
 </head>
 <body>
     <div class="container">
         <header>
-            <h1>🔥 Warm Sandbox Pool</h1>
-            <p class="subtitle">Pre-initialized OpenHands sandboxes with Ruby services ready to go</p>
+            <img class="brand-logo" src="{{ url_for('static', filename='openhands-logo.svg') }}" alt="OpenHands">
+            <div class="brand-text">
+                <h1>Warm Sandbox Pool</h1>
+                <p class="subtitle">Pre-initialized OpenHands sandboxes with Ruby services ready to go</p>
+            </div>
         </header>
 
         <div class="main-grid">
diff --git a/warm-sandbox-pool/templates/login.html b/warm-sandbox-pool/templates/login.html
index f01b3d1..8367541 100644
--- a/warm-sandbox-pool/templates/login.html
+++ b/warm-sandbox-pool/templates/login.html
@@ -4,13 +4,17 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Warm Sandbox Pool - Sign in</title>
+    <link rel="icon" type="image/svg+xml" href="{{ url_for('static', filename='favicon.svg') }}">
     <link rel="stylesheet" href="{{ url_for('static', filename='styles.css') }}">
 </head>
 <body>
     <div class="container">
         <header>
-            <h1>🔥 Warm Sandbox Pool</h1>
-            <p class="subtitle">Pre-initialized OpenHands sandboxes with Ruby services ready to go</p>
+            <img class="brand-logo" src="{{ url_for('static', filename='openhands-logo.svg') }}" alt="OpenHands">
+            <div class="brand-text">
+                <h1>Warm Sandbox Pool</h1>
+                <p class="subtitle">Pre-initialized OpenHands sandboxes with Ruby services ready to go</p>
+            </div>
         </header>
 
         <div class="panel login-panel">
diff --git a/warm-sandbox-pool/test_structure.py b/warm-sandbox-pool/test_structure.py
index bb6196f..92c979a 100644
--- a/warm-sandbox-pool/test_structure.py
+++ b/warm-sandbox-pool/test_structure.py
@@ -25,6 +25,8 @@ def check_structure():
         "templates/index.html",
         "templates/login.html",
         "static/login.js",
+        "static/openhands-logo.svg",
+        "static/favicon.svg",
     ]
 
     missing = []

From 41d33bb0d7bd8e5ca733a70347ea6b36a193925c Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 7 Oct 2026 20:05:29 +0000
Subject: [PATCH 9/9] warm-sandbox-pool: keep the example message in the box

The message box is now prefilled in the HTML and no longer cleared after a
claim, so each press of Start Conversation sends the example without
retyping. The grey placeholder only shows if the user empties the box.

Verified on beta: two claims in a row, no typing between them.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 warm-sandbox-pool/static/app.js        | 6 ------
 warm-sandbox-pool/templates/index.html | 4 ++--
 2 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/warm-sandbox-pool/static/app.js b/warm-sandbox-pool/static/app.js
index c570321..562a588 100644
--- a/warm-sandbox-pool/static/app.js
+++ b/warm-sandbox-pool/static/app.js
@@ -243,9 +243,6 @@ class PoolUI {
         const button = document.getElementById('start-btn');
         const resultArea = document.getElementById('result-area');
 
-        // Set default message
-        form.value = "Check if the quote service is running on localhost:4567 and fetch me a random quote. Show me the result.";
-
         button.addEventListener('click', async () => {
             const message = form.value.trim();
 
@@ -276,9 +273,6 @@ class PoolUI {
                 // Show success result
                 this.showResult(data, false);
 
-                // Clear input
-                form.value = '';
-
             } catch (error) {
                 console.error('Error starting conversation:', error);
                 this.showResult({ error: error.message }, true);
diff --git a/warm-sandbox-pool/templates/index.html b/warm-sandbox-pool/templates/index.html
index 4cb62f1..9a2f7fc 100644
--- a/warm-sandbox-pool/templates/index.html
+++ b/warm-sandbox-pool/templates/index.html
@@ -124,8 +124,8 @@ <h2>💬 Start a Conversation</h2>
                         <textarea
                             id="message-input"
                             rows="4"
-                            placeholder="Example: Check if the quote service is running on localhost:4567 and fetch me a random quote."
-                        ></textarea>
+                            placeholder="Describe what the agent should do in the warm sandbox."
+                        >Check if the quote service is running on localhost:4567 and fetch me a random quote. Show me the result.</textarea>
 
                         <button id="start-btn" class="btn-primary">
                             🚀 Start Conversation