Sandbox API directory

Find current core runtime, execution, supervised-process, task-registry, file, tunnel, and administration contracts without conflating deployment versions.

The generated core reference follows a selected public subset of the Node controller’s exported contract, with source-backed handler corrections. It is not a complete inventory of billing/provider/internal routes or a guarantee of hosted availability. Use the actual server’s /openapi.json and feature capabilities for its version.

Runtime and execution

Operation under /api/v1	Meaning
POST /sandbox/create	Admitted runtime creation with a retained request identity
GET /sandboxes, GET /sandbox/{id}	Authorized discovery/detail
GET /sandbox/{id}/status	Runtime state; independent from command/task success
POST /sandbox/{id}/stop, pause/resume/extend	Lifecycle transition and its actual acknowledgement
POST /sandbox/{id}/fork, promote	Workspace branch/promotion, not process-memory migration
POST /sandbox/{id}/execute	Bounded execution, optional SSE
GET /sandbox/{id}/executions/{executionId}	Original command outcome
POST /sandbox/{id}/executions/{executionId}/cancel	Cancellation request; inspect eventual termination
/sandbox/{id}/processes and process subroutes	Background workers, result/log/stdin/signal controls

See execution and recovery before implementing mutation retries or interpreting nullable exits.

Data and sharing

Canonical files use POST/GET/DELETE /sandbox/{id}/files, with /files/list for directory entries. Transport is base64 for file bytes. Checkpoints, snapshot/PVC branching and artifacts have separate consistency/retention boundaries; artifact checks reject changed bytes before writing into a sandbox.

Tunnel creation uses /sandbox/{id}/tunnels; closure uses /tunnels/{id}. Candidate shared recovery requires migration 069, DB-backed tunnel/idempotency storage, original request key, active matching receipt, and current authorization. See sharing contracts.

Agent and operator surfaces

/agent-tasks registers curated task metadata and family grants; it never starts a worker. /agent/sessions owns session lifecycle/context/budget. Private SDK task journals and server registry metadata preserve different state. See tasks and sessions.

Registration returns no usable key before verification. API keys, secrets, webhooks, governance, costs/timeline, audit, images and templates have their own scopes and enabled features. API-key ApiKey and JWT Bearer credentials are not interchangeable.

Source scope

Reviewed October 20, 2026 at 67bc2370: Node source, OpenAPI generator, concrete route handlers, and SDKs. Controller/SDK 2.12.0 is candidate work; compare recorded hosted state before using it. Start with the quickstart.