Sandbox SDK — stable package

Isolated Linux environments on Cloudflare Containers, driven from Workers.

Prefer the main Sandbox docs and installed stable types over memory. This skill is a gate, a contract, and a retrieval map—not a full manual.

This line is the current stable default npm package. The main Sandbox documentation describes it. Existing apps can stay here and keep shipping.

We recommend new projects on

@cloudflare/sandbox@next

with sandbox-next
. When you can, plan a move with sandbox-migrate-to-next
so you are ready when 1.0 becomes the stable release. Do not force that port unless the user asks.

1. Gate — confirm the package line

Before writing code, inspect the app:

Check	Must match
npm dependency	Default `@cloudflare/sandbox` (not `@next` / preview tags)
Container image	Matching stable image (not `cloudflare/sandbox:next` )

If you find…	Action
`@cloudflare/sandbox@next` or a `next` image	Stop. Load `sandbox-next` .
User wants to port to 1.0 / `@next`	Stop. Load `sandbox-migrate-to-next` . Do not half-apply preview APIs on a stable package.
Only cleaning deprecated stable APIs	Stay here; use the 2026 deprecation guide. That is not a move to `@next` .

Never mix a stable Worker package with an

@next

container image (or the reverse).

Skills install: Agent setup · cloudflare/skills

2. Contract — non-negotiables

```
await sandbox.exec(command)
```
takes a command string and resolves when the command finishes, with buffered
```
stdout
```
/
```
stderr
```
/
```
exitCode
```
(and related fields).
Long-running and streaming work use the stable command APIs (
```
startProcess
```
,
```
execStream
```
, and related helpers)—not the
```
@next
```
single-handle model. Open the Commands docs; do not invent
```
@next
```
```
output()
```
handles on stable.
Sessions can preserve working directory and environment across commands (default session /
```
enableDefaultSession
```
,
```
createSession
```
). See Sessions docs when state must carry across calls.
Interactive browser terminals often use sandbox.terminal(request)
and session/xterm helpers on stable—not preview
```
createTerminal
```
unless the package is
```
@next
```
.
Prefer RPC transport when using tunnels or large/binary streaming. HTTP/WebSocket transports are deprecated (cleanup guide below).
Files, mounts, ports, tunnels, backups, lifecycle, and interpreter: use main docs for signatures; trust installed stable types.
Non-secret config in sandbox env; live credentials in the Worker. Use outbound handlers when processes call external APIs.
Production preview hostnames need wildcard DNS on a custom domain when using those URL patterns.
Do not apply
```
@next
```
argv/
```
process.output()
```
APIs while the dependency is still stable.
Self-deployed bridge stays on the stable package and image. Bridge

Minimal shape:

import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success

3. Retrieve — open the doc for the task

Fetch the page before implementing. Installed stable types win over guesses.

You need to…	Open
Orient	Sandbox overview
First Worker, template, Docker	Get started
`exec` , streaming, background processes	Commands API · Execute commands · Background processes · Streaming output
Sessions / shell state across commands	Sessions concept · Sessions API
`getSandbox` options, sleep, destroy	Lifecycle API · Sandbox options
Env vars	Environment variables
Files	Files API · Manage files · File watching
Buckets / mounts	Storage API · Mount buckets
Backups	Backups API · Backup and restore
Ports, preview URLs, expose	Ports API · Expose services
Tunnels	Tunnels API
Proxy / Workers connections	Proxy requests · Workers connections
Browser / PTY terminal	Terminal API · Terminal concept · Browser terminals
Code interpreter	Interpreter API · Code execution
Git in the sandbox	Git workflows
Secrets / egress	Outbound traffic
WebSockets	WebSocket connections
Docker-in-Docker	Docker in Docker
Production deploy	Production deployment
Containers concept	Containers
How-to index	Guides
API index	API reference
Deprecated APIs while staying on stable	2026 deprecation guide
Self-deployed bridge	Bridge · Bridge HTTP API
Examples (stable/ `main` )	examples on GitHub
New work on 1.0 preview	`sandbox-next` · 1.0 preview
Port existing app to `@next`	`sandbox-migrate-to-next` · Migrate

Deprecated-API cleanup (stay on stable)

Update package + matching image first, then follow the guide. Typical search:

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

This path does not switch you to

@next

4. Before you ship

Worker package and container image on the same stable line
Typecheck against installed stable types
No live secrets in sandbox env
If using deprecated transports/helpers, finish or track 2026 deprecation cleanup
When the team is ready for 1.0, use sandbox-migrate-to-next
—do not force cutover unprompted

sandbox-stable

NPX Install

Tags

SKILL.md Content