cloudflare/sandbox-next

Sandbox SDK — @next (1.0 preview)

Isolated Linux environments on Cloudflare Containers, driven from Workers.

Prefer preview docs and installed @next types over memory. APIs change; this skill is a gate, a contract, and a retrieval map—not a full manual.

We recommend new projects on this line. Apps still on the default package use sandbox-stable. Port only when asked, via sandbox-migrate-to-next.

1. Gate — confirm the package line

Before writing code, inspect the app:

| Check | Must match | | ----- | ---------- | | npm dependency | @cloudflare/sandbox@next (or another preview tag) | | Container image | Same line (e.g. cloudflare/sandbox:next, next-python) |

| If you find… | Action | | ------------ | ------ | | Default @cloudflare/sandbox (no @next) | Stop. Load sandbox-stable. Do not apply this skill’s APIs. | | User wants to port stable → @next | Stop. Load sandbox-migrate-to-next. | | Self-deployed bridge only | Bridge is not on the 1.0 preview line yet. Keep bridge on stable package + image. Bridge (stable) |

Never mix an @next Worker package with a stable container image (or the reverse).

Skills install: Agent setup · cloudflare/skills

2. Contract — non-negotiables

• sandbox.exec(argv) takes an argv list and resolves when the process starts. It returns a handle, not a finished command result.
• Collect results with handle methods: output(), logs(), waitForExit(), waitForPort(), waitForLog(), kill(signal?).
• No implicit shell. Shell syntax needs an explicit shell, e.g. ["/bin/bash", "-lc", script].
• Each launch is independent. A cd / export in one exec is not visible to the next. Pass cwd and env per launch, or one shell script.
• Process handles have no stdin. Interactive use → terminals (createTerminal + connect).
• Local wait timeout / AbortSignal cancel the wait only. They do not kill the process. Use kill or exec’s remote timeout.
• getProcess / listProcesses / getTerminal / listTerminals do not start a container; they return null / [] when none is up.
• Process and terminal IDs belong to the current container, not forever to a sandbox ID. For work that must survive replace, store the full job (argv, cwd, env, app state)—not only an id.
• Non-secret config only in setEnvVars / launch env. Live credentials stay in the Worker; use outbound handlers when the sandbox calls external APIs.
• Do not invent removed stable APIs (gitCheckout on core, string-exec completion, session execution, sandbox.terminal(request)).
• Do not use one retry loop for every error (see Errors docs).

Minimal shape:

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

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
const result = await process.output({ encoding: "utf8" });
// result.stdout, result.exitCode

Optional non-exhaustive cheatsheet (process/terminal/interpreter only): references/api-quick-ref.md
Examples index (next branch): references/examples.md

3. Retrieve — open the doc for the task

Fetch the page before implementing. Installed @next types win over guesses.

| You need to… | Open | | ------------ | ---- | | Orient / choose preview | 1.0 preview overview | | First Worker, wrangler, Dockerfile | Get started | | exec, handles, readiness, durability | Process execution | | Process API signatures | Processes API | | Sandbox ID vs container vs sleep/destroy | Lifecycle | | cwd / env / setEnvVars | Environment | | Interactive PTY / browser terminal | Terminals · Terminals API | | Python/JS code interpreter | Interpreter · Interpreter API | | Extensions model | Extensions | | Error classes and recovery | Errors · Errors API | | Common failures | Troubleshooting | | API hub | API reference | | Files, mounts, backups, ports, tunnels, proxyToSandbox | Main docs for shared surfaces (ignore stable-only session/transport/sandbox.terminal): Files · Storage / mounts · Ports · Tunnels · Backups · Outbound traffic · Expose services · Production | | Example apps | examples on next | | Still on stable package | sandbox-stable · Main Sandbox docs | | Porting an existing stable app | sandbox-migrate-to-next · Migrate |

4. Before you ship

• Lockfile and Dockerfile on the same @next line
• Typecheck against installed @next types
• No live secrets in sandbox env
• Production preview hostnames need wildcard DNS on a custom domain when using those URL patterns