concepts

Sandboxes

Isolated Firecracker microVMs — one per agent or worker.

Sandboxes are created inside a room from a template. Each needs:

• agent_id — stable name in the room (e.g. a1, coder, browser)
• guest_cid — unique int in the room, typically 9100–9999
• memory_mib — RAM budget for the template
• optional template_id, env, egress_allowlist

Create

Prefer MCP sandbox_create or REST POST …/sandboxes/from-template.

Creates use a warm pool when available. If the pool is empty you may see HTTP 503 — wait and retry, or check health.

Exec

sandbox_exec / POST …/sandboxes/{agent_id}/exec runs a command inside the guest. Confirm exit code 0 for hello paths.

Destroy

sandbox_destroy or room destroy. Drive files for the room follow room lifecycle.

Related

• Create & exec
• Standby & resume
• Ports & preview