Chapter 28
Self-Hosted Sandboxes
Self-Hosted Sandboxes
Reference implementations for running Claude Managed Agents sessions against self-hosted execution sandboxes. Each variant implements the same contract on a different compute provider:
- Receive the
session.status_run_startedwebhook (verified withclient.beta.webhooks.unwrap()). - Drain the environment work queue so a single delivery recovers any earlier missed items.
- Per work item, launch a per-session sandbox that runs the SDK/CLI tool
runner (
bash/read/write/edit/glob/grep), heartbeats the lease, and poststool_results back to the session.
No org API key reaches the runner — the sandbox authenticates with the environment key, the single credential for both the control plane and the per-session calls.
| Variant | Compute | Runner |
|---|---|---|
docker/ | Plain Docker on a host you control | ant beta:worker run in a per-session container |
cf/ | Cloudflare Containers | ant beta:worker run in a per-session Cloudflare Container |
cf-worker/ | Cloudflare Workers (no container) | TS SessionToolRunner in a Durable Object with an in-isolate fake filesystem |
modal/ | Modal | Python sandbox_runner.py in a Modal Sandbox with a per-session Volume |
daytona/ | Daytona | Same sandbox_runner.py uploaded to a Daytona sandbox |
vercel/ | Vercel Functions + Sandbox | Node runner.mjs in a Vercel Sandbox |
Getting started
See docs/usage-guide.md for the full flow: creating a
self-hosted environment, registering the webhook, and wiring up the
environment key. Each variant's README.md covers its provider-specific
deploy steps.
See docs/upgrade-guide.md for migrating between SDK
versions.