OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add cloudflare/skills --skill sandbox-migrate-to-next
Migrate Cloudflare Sandbox apps from stable @cloudflare/sandbox to @cloudflare/sandbox@next (SDK 1.0 preview). Use sandbox-next for apps already on the preview.
npx skills add cloudflare/skills --skill sandbox-migrate-to-next
@next)Perform the port. Follow the steps in order. Depth lives in docs—fetch the linked page when a step needs detail.
Human guide: Migrate · 1.0 preview
New projects should start on @next (sandbox-next), not this skill. Day-to-day stable work → sandbox-stable. Deprecated-API cleanup without moving to @next → 2026 deprecation guide first if needed.
Existing apps should migrate when you can, so you are ready when 1.0 becomes the stable release. Do not force production cutover without the user agreeing.
Prefer installed @next types and the migrate doc over memory.
Stop after any step that needs a user decision.
@next line.@next control protocols are incompatible both ways; gradual rollout leaves a broken mixed window. In-flight container work can stop.await sandbox.exec(...) means process started, not command finished.timeout / AbortSignal cancel the wait only, not the process.gitCheckout on core, process stdin, string-exec completion helper).| Stable | @next |
|---|---|
SANDBOX_TRANSPORT / transport / setTransport | Remove — RPC only |
await sandbox.exec("cmd") → buffered result | await sandbox.exec(argv) → handle, then output / waits |
execStream / startProcess | Same handle: logs, waitFor*, kill |
| Default / named sessions | Gone — cwd/env per launch, or one shell script |
sandbox.terminal(request) / session terminal | createTerminal + terminal.connect(request) |
xterm sessionId | terminalId |
Interpreter methods on Sandbox | withInterpreter → sandbox.interpreter.* |
gitCheckout | argv git via exec |
| String kill signals | Numeric only |
Files, mounts, backups, ports, tunnels, proxyToSandbox | Mostly unchanged (ignore session/transport bits on stable pages) |
Depth: Migrate · after port, day-to-day → sandbox-next
Also: string exec(, cd then a later exec, bare createCodeContext / runCode on Sandbox.
--containers-rollout=immediate (live processes/terminals/streams may stop)?-python image variant?Same prerelease tag on Worker and image when not on floating next.
Apply replacements from the map. For each area, implement from the doc—not from stable habits:
| Area | Doc |
|---|---|
| Commands / handles / waits | Processes · Processes API |
cwd / env / secrets | Environment · Outbound traffic |
| Drop sessions | Migrate · Lifecycle |
| Terminals | Terminals |
| Interpreter | Interpreter |
| Errors | Errors |
| Durable job across requests | Process execution — lifetime / durability |
Commands (shape):
Terminals (shape):
Interpreter (shape):
Git (shape):
Delete transport settings entirely. Remove session APIs. Isolate users with separate sandbox IDs.
Staging/branch first. Production is one deploy of matching Worker + image:
Leave rollout_active_grace_period at default 0 (or set 0 if raised). After cutover, pre-deploy process/terminal IDs are invalid. Details: Migrate · Container rollouts
@next line@nextexec + output({ encoding: "utf8" })--containers-rollout=immediateThen day-to-day work uses sandbox-next.
@next Worker with stable image (or reverse)await exec as command completioncd / exports persist across exec callsgitCheckout, process stdin, or undocumented APIssetEnvVars / launch env// Before (stable)
const result = await sandbox.exec("npm test");
// After (@next)
const process = await sandbox.exec(["/bin/bash", "-lc", "npm test"]);
const result = await process.output({ encoding: "utf8" });const server = await sandbox.exec(["/bin/bash", "-lc", "npm run dev"], {
cwd: "/workspace/app",
});
await server.waitForPort(3000, { timeout: 60_000 });
await server.kill(); // numeric; default 15const terminal = await sandbox.createTerminal({ command: ["bash"], cwd: "/workspace" });
const t = await sandbox.getTerminal(terminal.id);
if (!t) return new Response("terminal gone", { status: 410 });
return t.connect(request, { cursor, cols, rows });import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
import { withInterpreter } from "@cloudflare/sandbox/interpreter";
export class Sandbox extends BaseSandbox<Env> {
interpreter = withInterpreter(this);
}const clone = await sandbox.exec(
["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
{ cwd: "/workspace" },
);
const result = await clone.output({ encoding: "utf8" });npx wrangler deploy --containers-rollout=immediate