Skip to main content
@stateset/sandbox-sdk is the TypeScript/Node client. The reviewed candidate source is 2.12.0; package publication and hosted feature availability must be checked separately. Use Node.js 20.19+ on the 20.x line or 22.12+ for the source workspace.

Build the reviewed source

From the stateset-sandbox repository:
For a published compatible release, install @stateset/sandbox-sdk in your application. The repository build does not publish a registry package. Use the deployment origin without /api/v1; the client adds that API prefix.

Create, inspect, and clean up

Use an admitted isolation tier and actual credentials. A returned stop acknowledgement requires a separate status/cleanup check. If creation loses its response before returning an ID, retain its supported request key and inspect the original request rather than creating another runtime under a fresh identity. startupTimeoutMs is client-only, accepts 1–600,000 ms, and affects creation’s request budget. It is not sent to the controller and does not extend sandbox lifetime or ordinary read requests. timeout_seconds includes startup; execution timeout uses milliseconds.

Files and interpreter state

File bytes cross the wire as base64. The Node controller’s canonical read/write route is /api/v1/sandbox/{id}/files; directory listing uses /files/list. CodeInterpreter uses a persistent Python REPL when available. Its script mode uses a fresh process; disabled REPL or unavailable Jupyter can trigger a labeled fallback. Pause/recovery cannot preserve the kernel’s RAM.

Processes, tasks, and sharing

client.executions exposes original execution reads, cancellation, bounded waits, and replay. client.processes manages supervised workers, logs, results, stdin, and signals. Check actual status, nullable exit code, outcome, and output completeness. AgentTasks plus FileAgentTaskStore retain private prepared-task journals. The store is exported from @stateset/sandbox-sdk/node; browser consumers do not get a filesystem journal. AgentTeams and server registry observation have their own identity and permission rules. See prepared tasks. Persist CreateTunnelOptions.idempotencyKey with the original target/body before opening a tunnel. Shared DB tunnel recovery needs migration 069 and compatible idempotency storage; it is not implied by installing SDK 2.12.0. See tunnels and artifacts. StateSetSandboxExtended exposes additional checkpoint/artifact/administration helpers. DurableRunClient calls the separate Temporal control plane; the local MultiAgentOrchestrator does not persist its scheduler after caller restart. Source: sdk/src, sdk/README.md, and package metadata at 67bc2370. Continue with execution recovery or the terminal workbench.
Last modified on October 20, 2026