Sandboxes and sessions

Create

Every sandbox starts with POST /sandboxes. Common fields:

{
  "templateID": "python",
  "timeout": 900,
  "metadata": {"job":"demo"},
  "allowInternetAccess": true,
  "lifecycle": {"onTimeout":"pause","autoResume":true}
}

Templates choose the backend. Jail templates are fast and lightweight. bhyve templates run a full guest kernel for Linux, Windows, GPU, and VM-only cases.

Work inside it

• Shell tabs in /ui/ use /sandboxes/:id/ws.
• SDK run_code uses envd /execute.
• SDK commands use /process.Process/*.
• File APIs use /files or the explicit /sandboxes/:id/files aliases for the browser UI.
• Browser tabs proxy Chrome DevTools through /cdp-proxy/:id/.
• VS Code tabs proxy code-server through /vscode-proxy/:id/.
• VNC/RDP tabs proxy desktop sessions through /vnc-proxy/:id/ and /rdp-proxy/:id/.

Pause, resume, and TTL

Jail-backed sandboxes and bhyve SSH guests can pause on timeout with process memory preserved on the same host. If autoResume is enabled, shell/files/envd activity resumes the sandbox and refreshes the timeout. For bhyve, paused pool entries remain owned by the sandbox and are not available for checkout by another caller.

Use this for agents that go idle between tool calls. Use kill timeouts for one-shot jobs where preserving state does not matter.

Snapshot and fork

Use durable snapshots when you want a reusable filesystem fork point:

curl -X POST /sandboxes/<id>/snapshots
curl -X POST /snapshots/<snapshot-id>/fork

The admin dashboard exposes the same action as snapshot + fork in the machine table and links the fork back into the demo UI.

Teardown

DELETE /sandboxes/:id is authoritative. It stops commands, unmounts live volumes, tears down network anchors, releases the IP, and destroys the clone or returns a bhyve pool entry.