skills.rest
cloudflare
cloudflareOFFICIAL
Explore all skills by this author →
WebsiteGitHub

sandbox-migrate-to-next

Migrates Cloudflare Sandbox apps from stable @cloudflare/sandbox to the @next 1.0 preview.

2.8k|267|Updated Dec 10, 2025
Search Tags:#containers#cloudflare#wrangler#workers#Migration#SDK upgrade#Sandbox
One-click install
npx skills add https://github.com/cloudflare/skills --skill sandbox-migrate-to-next
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sandbox-migrate-to-next
Source: https://github.com/cloudflare/skills/tree/main/skills/sandbox-migrate-to-next
Command: npx skills add https://github.com/cloudflare/skills --skill sandbox-migrate-to-next

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @cloudflare/sandbox.

What problem does it solve?

Porting a Cloudflare Sandbox application from the stable @cloudflare/sandbox package to the @next (Sandbox SDK 1.0 preview) line involves breaking API changes—removed sessions, transport settings, and buffered exec results—that are easy to get wrong. This Skill provides a structured audit, replacement map, and cutover procedure so the migration is complete and consistent.

Core Features & Use Cases

  • Codebase Audit: Grep patterns locate every stable-only API usage (SANDBOX_TRANSPORT, sessions, execStream, gitCheckout, string kill signals) that must be replaced.
  • Replacement Map: A stable-to-@next mapping table plus code shapes for argv-based exec with process handles, createTerminal/connect terminals, withInterpreter, and git via argv.
  • Safe Production Cutover: Enforces matching Worker package and container image versions and an immediate container rollout via wrangler, avoiding a broken mixed-protocol window.
  • Use Case: You have a production Worker using stable Sandbox sessions and buffered exec calls. Run this Skill to audit the code, rewrite call sites to the @next handle-based API, upgrade the Dockerfile image, and deploy with --containers-rollout=immediate.

Quick Start

Migrate my Cloudflare Sandbox app from the stable @cloudflare/sandbox package to @cloudflare/sandbox@next and update the code, Dockerfile, and deployment accordingly.

Frequently Asked Questions about sandbox-migrate-to-next

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate from @cloudflare/sandbox stable to @next?▼

Audit your code for removed APIs (sessions, transport settings, buffered exec), install @cloudflare/sandbox@next, switch the Dockerfile to the cloudflare/sandbox:next image, rewrite call sites using the replacement map, then deploy with wrangler using --containers-rollout=immediate.

What replaced sandbox.exec in the Sandbox SDK 1.0 preview?▼

In @next, sandbox.exec takes an argv array and returns a process handle immediately; it no longer waits for command completion. Call output({ encoding: "utf8" }) or the waitFor* methods on the handle to get results, and use an explicit shell binary for shell syntax.

Can I do a gradual container rollout when migrating to Sandbox @next?▼

No. Stable and @next control protocols are incompatible in both directions, so a gradual rollout leaves a broken mixed window. Production cutover must be a single deploy with --containers-rollout=immediate, and in-flight container work may stop.

Does the Sandbox 1.0 preview still support sessions and gitCheckout?▼

No. Default and named sessions are removed; pass cwd and env per launch instead. gitCheckout is also gone—run git through argv-based exec, for example cloning with ["git", "clone", "--depth", "1", repoUrl, path].

When should I not use the sandbox migration skill?▼

Do not use it for new projects, which should start directly on @next with the sandbox-next skill, or for day-to-day stable work covered by sandbox-stable. It is only for porting existing stable apps to the 1.0 preview.

Related Skills

Explore More Software Engineering Skills→
mpsuessermpsuesser

sandbox-sdk

Execute shell commands and AI-generated code in Cloudflare Workers sandboxes.

Community
Advanced
yash-gargyash-garg

sandbox-sdk

Builds isolated Cloudflare Sandbox SDK environments for executing untrusted code.

Community
Advanced
RonanCodesRonanCodes

cf-ship

Automate TanStack Start and Cloudflare Workers deployments with pre-flight checks.

Community
Advanced
try-workstry-works
95

sandbox-2026-deprecation

Identify deprecated Cloudflare Sandbox SDK APIs and suggest replacements.

Community
Intermediate