Start Sandbox

• sandbox_demo_brief.py — ~25 lines, one-numbered-step-per-block, minimal error handling. Best for quickly understanding the API shape.
• sandbox_demo.py — same flow but split into a main() function with docstrings and type hints, more in line with the rest of the repo.

Want to go further? clone-and-attach builds on this example: it clones a repo and runs its .openhands/setup.sh in the sandbox, then attaches a conversation to the prepared sandbox.

​

APIs Used

​

1. Cloud App Server — manages the sandbox lifecycle

• Base URL: https://app.all-hands.dev
• Auth header: X-Session-API-Key: <OH_API_KEY>
• Endpoints:
  • POST /api/v1/sandboxes — start a sandbox (optional ?sandbox_spec_id=…)
  • GET /api/v1/sandboxes?id=<id> — batch-get sandboxes by id (returns SandboxInfo with status, session_api_key, exposed_urls, …)

​

2. Agent Server — runs inside the sandbox

• Base URL: the entry in sandbox.exposed_urls with name == "AGENT_SERVER". Inside the container the agent server listens on port 60000 (you’ll see that in the sample ps -ef output below and in the port field of the exposed_urls entry); it is reverse-proxied to the public HTTPS URL, so you always talk to it over https://… (port 443) — never the internal port.
• Auth header: X-Session-API-Key: <session_api_key> returned by the sandbox-create call (different from your Cloud API key)
• All routes are under /api/.... This example uses:
  • POST /api/bash/execute_bash_command — run a bash command and wait for its result; body { "command": "...", "timeout": 30, "cwd": "..." }, response includes stdout, stderr, exit_code

Full Agent Server schema is available at <agent_server_url>/openapi.json once the sandbox is RUNNING.

​

What it prints

sandbox: 59Ji2kvkUtZZSm7zAkAxwN
  status: RUNNING
agent: https://rzwfxneubhwcfpav.prod-runtime.all-hands.dev

=== ls -la /workspace ===
drwxr-sr-x bash_events
drwxr-sr-x conversations
drwxrws--- lost+found

=== agent-server process ===
openhan+ 1  /usr/local/bin/openhands-agent-server --port 60000
openhan+ 38 /usr/local/bin/openhands-agent-server --port 60000

​

Run it

export OH_API_KEY=...       # your https://app.all-hands.dev API key
pip install requests
python sandbox_demo_brief.py   # or sandbox_demo.py

SID=<sandbox_id>
curl -X DELETE "https://app.all-hands.dev/api/v1/sandboxes/${SID}?sandbox_id=${SID}" \
     -H "X-Session-API-Key: $OH_API_KEY"

​

Notes

• A freshly created sandbox starts in STARTING; session_api_key and exposed_urls are null until it becomes RUNNING. Polling every few seconds is sufficient.
• The Cloud API has no single-sandbox GET /sandboxes/{id} — use the batch-get endpoint GET /sandboxes?id=<id> and read the first item.
• To pick a specific runtime image, pass ?sandbox_spec_id=<id> to the POST /api/v1/sandboxes call. List available specs with GET /api/v1/sandbox-specs/search.

​

Related