Migrate stable → Sandbox SDK 1.0 preview (

@next

)

@next

sandbox-next

sandbox-stable

@next

@next

Workflow

1. Review hard rules and the replacement map
2. Audit the codebase; list hits and target shapes
3. Clarify with the user (cutover, bridge, Python image, unclear sites)
4. Upgrade package, image, and code
5. Validate

Hard rules

• Worker package and container image must be the same

  @next

  line.
• Production cutover uses immediate container rollout. Stable and

  @next

  control protocols are incompatible both ways; gradual rollout leaves a broken mixed window. In-flight container work can stop.
• After cutover,

  await sandbox.exec(...)

  means process started, not command finished.
• Argv is as-is (no implicit shell). Shell syntax needs an explicit shell binary.
• Process handles have no stdin → terminals for interactive input.
• Observation

  timeout

  /

  AbortSignal

  cancel the wait only, not the process.
• No single retry loop for every error.
• Do not invent APIs (

  gitCheckout

  on core, process stdin, string-exec completion helper).
• Self-deployed bridge stays on stable (not part of the preview line yet).

Replacement map

@next

SANDBOX_TRANSPORT

transport

setTransport

await sandbox.exec("cmd")

await sandbox.exec(argv)

output

execStream

startProcess

logs

waitFor*

kill

cwd

env

sandbox.terminal(request)

createTerminal

terminal.connect(request)

sessionId

terminalId

Sandbox

withInterpreter

sandbox.interpreter.*

gitCheckout

git

exec

proxyToSandbox

sandbox-next

Audit

rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'

exec(

cd

exec

createCodeContext

runCode

Sandbox

Clarify (ask when needed)

• OK to cut production with

  --containers-rollout=immediate

  (live processes/terminals/streams may stop)?
• Self-deployed bridge? Leave on stable.
• Python interpreter →

  -python

  image variant?
• Call sites not covered by the map?

Upgrade

Package and image

npm install @cloudflare/sandbox@next

FROM cloudflare/sandbox:next
# Python: cloudflare/sandbox:next-python

next

Code by area

cwd

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 15

const 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" });

Deploy cutover

npx wrangler deploy --containers-rollout=immediate

rollout_active_grace_period

0

0

Validate

1. Lockfile + Dockerfile on the same

   @next

   line
2. Typecheck against

   @next

3. Smoke argv

   exec

   +

   output({ encoding: "utf8" })

4. Smoke long process / terminal / interpreter if used
5. Errors distinguished: unavailable / interrupted-RPC / stale / local wait
6. No live secrets in sandbox env
7. Grep again for removed APIs
8. Production used

   --containers-rollout=immediate

sandbox-next

Red flags — stop and fix

• Mixing

  @next

  Worker with stable image (or reverse)
• Gradual container rollout for this cutover
• Treating

  await exec

  as command completion
• Assuming

  cd

  / exports persist across

  exec

  calls
• One retry wrapper for every error
• Inventing

  gitCheckout

  , process stdin, or undocumented APIs
• Keeping pre-cutover process/terminal IDs after deploy
• Forcing production cutover without user agreement
• Putting live secrets in

  setEnvVars

  / launch

  env