cloudflare/sandbox-stable

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