name: sandbox-stable description: Build or maintain Cloudflare Sandbox apps on the stable @cloudflare/sandbox package. Use sandbox-next for preview apps and sandbox-migrate-to-next for stable-to-preview migrations. ---

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:

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.

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