@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