Sandbox SDK 1.0 is the next major release of the SDK. It is available now as a preview on the npm @next tag. The current stable package remains published for existing apps.
Sandbox still runs isolated work on Cloudflare Containers. The 1.0 preview is a thinner SDK on that foundation: one process handle for short and long-running work, no session-based command state, no transport picker, terminals as first-class PTYs, and the code interpreter as an opt-in extension.
We recommend that new projects start on @cloudflare/sandbox@next and follow this section. Existing apps should migrate when you can, so you are ready when 1.0 becomes the stable release. Follow Migrate.
The main Sandbox documentation still documents today's stable package. Use this section for preview APIs and the migration path.
npm i @cloudflare/sandbox@nextyarn add @cloudflare/sandbox@nextpnpm add @cloudflare/sandbox@nextbun add @cloudflare/sandbox@nextDeploy the Worker package and the sandbox container image from the same preview line. Do not mix a preview Worker package with a stable container image (or the reverse). Cutover details, including container rollout, are in Migrate.
The stable package grew several ways to run commands (exec, startProcess, execStream), optional session state across launches, and selectable transports between the Durable Object and the container. That surface worked, but it duplicated ideas and hid how sandboxes actually behave on containers.
The preview collapses that toward a smaller contract:
| You want… | In the preview |
|---|---|
| Run a program | exec(argv) → process handle when launch succeeds |
| See output or wait for readiness | output(), logs(), waitForExit(), waitForLog(), waitForPort() on the handle |
| Stop a process | kill(signal?) (numeric signal; default 15) |
| Keep shell state across many interactive steps | A terminal (PTY), not a hidden default session |
| Run Python / JS cells | Code interpreter extension on your Sandbox subclass |
| Talk to the container control plane | Always RPC — no transport setting |
Procedures: Migrate. Mental model: Process execution and Sandbox lifecycle.
Stable: sandbox.exec(string) resolves when the command finishes with buffered output. Long-running services and streaming use separate APIs (startProcess, execStream).
Preview: sandbox.exec() takes argv and resolves when the process starts. The same handle covers short commands and long-running services.
// Current stable package
const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);
// 1.0 preview
const process = await sandbox.exec(["npm", "test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);// Current stable package
const result = await sandbox.exec("npm test");
console.log(result.stdout, result.exitCode);
// 1.0 preview
const process = await sandbox.exec(["npm", "test"]);
const result = await process.output({ encoding: "utf8" });
console.log(result.stdout, result.exitCode);Shell features such as pipes and && need an explicit shell, for example ['/bin/bash', '-lc', 'cd app && npm test']. Pass cwd and env on each exec() when the process needs them. Details: Process execution, Processes API.
Stable: a default session can preserve working directory and environment variables across exec() calls. Apps can also create named sessions with createSession().
Preview: no session execution on the SDK. Each exec() is independent. Pass cwd and env on each launch, or put multi-step shell syntax in one explicit shell argv. Isolate end users with separate sandboxes, not sessions inside one sandbox. Environment model: Environment variables.
Stable: browser shells often use sandbox.terminal(request) with session helpers and xterm sessionId.
Preview: terminals are PTY resources — createTerminal, getTerminal, listTerminals, and terminal.connect(request). The xterm helper uses terminalId. Refer to Terminals.
Stable: interpreter methods live on Sandbox.
Preview: attach the interpreter on your subclass, then call sandbox.interpreter.*. Refer to Code interpreter.
Stable: apps can select HTTP, WebSocket, or RPC between the Durable Object and the container.
Preview: the SDK always uses RPC. Remove SANDBOX_TRANSPORT, the transport option on getSandbox(), and setTransport(). No replacement setting is required.
This is not a new container product. You still address a sandbox with a stable sandbox ID:
const sandbox = getSandbox(env.Sandbox, "user-123");const sandbox = getSandbox(env.Sandbox, "user-123");That sandbox runs in a container. The ID is stable. The container instance behind it is not always the same one. Processes and terminals you start exist only in the current container. When that container stops or is replaced, those processes and terminals are gone — old handles fail closed instead of quietly attaching to a new container for the same sandbox ID.
Container stop and replace already happened on the stable line. The preview makes process and terminal APIs honest about that lifetime. Full model: Sandbox lifecycle. Process detail: How long a process lives. Recovery: Errors and recovery.
These remain available. Use the main Sandbox documentation for signatures, and ignore session or transport options where those pages still mention them:
- Files and file watching
- Storage and backups
- Ports and tunnels
- Lifecycle options and sandbox options (except removed session/transport fields)
- Outbound traffic (credential injection and egress policy)
For process environment on @next, use Environment variables in this section.
Get started
Install @next and run your first process handle.
Migrate from stable
Update an existing app, including deploy cutover on @next.
Sandbox lifecycle
Sandbox ID, container, stop, replace, and what your app should store.
Process execution
How exec() works, process handles, and how long processes live.
Terminals
Interactive PTYs, lifetime, and browser connect.
Errors and recovery
How to retry, inspect, and relaunch after common failures.
Environment variables
setEnvVars, per-launch env, and how processes get their environment.
Code interpreter
Attach the interpreter extension and run Python or JS/TS.
API reference
Process, terminal, error, and interpreter signatures for @next.
Extensions
Attach the code interpreter and other optional capabilities.
Troubleshooting
Common @next failures and where to fix them.
Install Cloudflare Skills ↗ for your agent (Agent setup). Use sandbox-next for work on @next (recommended for new projects). Existing apps on the current stable package should use sandbox-stable until you are ready to move, then sandbox-migrate-to-next. Deprecated-API cleanup while staying on stable is covered in the 2026 deprecation guide and sandbox-stable.
While you remain on the current stable package, use the main docs: