gabrielmoreira 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 bufferedstdout/stderr/exitCode(and related fields).- Long-running and streaming work use the stable command APIs (
startProcess,execStream, and related helpers)—not the@nextsingle-handle model. Open the Commands docs; do not invent@nextoutput()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 previewcreateTerminalunless 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
@nextargv/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