sandbox-migrate-to-next

Install @cloudflare/sandbox@next, switch the Dockerfile to cloudflare/sandbox:next, and apply the replacement map: buffered exec becomes handle-based exec with output() waits, sessions are removed in favor of per-launch cwd/env, and sandbox.terminal becomes createTerminal plus connect. Deploy production with --containers-rollout=immediate.

exec now takes an argv array and returns a process handle; awaiting it means the process started, not finished, so use output() or waitFor* methods for results. Default and named sessions are removed—pass cwd and env per launch or run one shell script instead.

No. Stable and @next control protocols are incompatible both ways, so a gradual rollout leaves a broken mixed window. Production cutover must use wrangler deploy --containers-rollout=immediate, accepting that in-flight processes and terminals may stop.

No. The self-deployed bridge stays on the stable line and is not part of the @next preview. If your app uses a self-deployed bridge, leave that component on stable while migrating the rest.

Argv is passed as-is with no implicit shell, so pipes, redirects, and cd do not work directly. Invoke an explicit shell binary such as ["/bin/bash", "-lc", "your command"] to get shell behavior.

Skip it for day-to-day stable sandbox work, which belongs to sandbox-stable, and for brand-new projects, which should start directly on @next with sandbox-next. Also avoid it for deprecated-API cleanup that does not move to the preview line.