skills.rest
julianckt
juliancktCOMMUNITY
Explore all skills by this author →
GitHub

sandbox-migrate-to-next

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

Updated Jul 31, 2026
Search Tags:#migration#sdk#containers#cloudflare#wrangler#sandbox#workers
One-click install
npx skills add https://github.com/julianckt/adoptarun --skill sandbox-migrate-to-next-julianckt
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sandbox-migrate-to-next
Source: https://github.com/julianckt/adoptarun/tree/main/.agents/skills/sandbox-migrate-to-next
Command: npx skills add https://github.com/julianckt/adoptarun --skill sandbox-migrate-to-next-julianckt

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @cloudflare/sandbox.

What problem does it solve? Cloudflare Sandbox apps built on the stable @cloudflare/sandbox SDK use APIs (sessions, transport settings, buffered exec, gitCheckout) that are removed or reshaped in the SDK 1.0 preview. This Skill performs the port to @cloudflare/sandbox@next systematically, avoiding broken mixed-version deployments and invented APIs. ## Core Features & Use Cases - Structured migration workflow: Audit the codebase with grep patterns, clarify cutover decisions with the user, upgrade package and container image, then validate. - Replacement map: Maps stable APIs (SANDBOX_TRANSPORT, execStream, sessions, sandbox.terminal, gitCheckout) to their @next equivalents (argv exec handles, createTerminal, withInterpreter). - Safe production cutover: Enforces matching Worker/image versions and immediate container rollout via wrangler deploy --containers-rollout=immediate. - Use Case: You have a Worker using stable sandbox sessions and buffered exec calls. Run this Skill to audit call sites, rewrite them to argv-based process handles, swap the Dockerfile to cloudflare/sandbox:next, and deploy with immediate rollout. ## Quick Start Migrate my Cloudflare Sandbox Worker from the stable @cloudflare/sandbox package to the @next SDK 1.0 preview, updating the package, container image, and all API call sites.

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 stable @cloudflare/sandbox to the 1.0 preview?▼

Install @cloudflare/sandbox@next, switch the Dockerfile to cloudflare/sandbox:next, then rewrite API calls per the replacement map: buffered exec becomes argv exec returning a process handle, sessions are removed in favor of per-launch cwd/env, and terminals use createTerminal plus terminal.connect.

What replaces sandbox.exec in the Cloudflare Sandbox 1.0 preview?▼

sandbox.exec now takes an argv array and returns a process handle immediately, meaning the process started rather than finished. Call process.output({ encoding: "utf8" }) to await the buffered result, or use logs, waitForPort, and kill on the handle.

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

No. Stable and @next control protocols are incompatible both ways, so gradual rollout leaves a broken mixed window. Production cutover requires one deploy with wrangler deploy --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 or use one shell script instead. gitCheckout is also gone—run git via an argv exec call such as ["git", "clone", "--depth", "1", repoUrl, path].

Why does my migrated sandbox code fail after deploying to production?▼

Common causes are mixing an @next Worker with a stable container image, treating await exec as command completion, assuming cd or exports persist across exec calls, or reusing pre-cutover process and terminal IDs, which become invalid after deploy.

Related Skills

Explore More Software Engineering Skills→
cloudflarecloudflare
2.8k

sandbox-migrate-to-next

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

Official
Advanced
lettucebolettucebo

sandbox-next

Build Cloudflare Sandbox apps on the @cloudflare/sandbox@next 1.0 preview SDK.

Community
Advanced
linguositylinguosity

dreamlink-dev-workflow

Automates typecheck, lint, and build error detection and fixes across Dreamlink development pipelines.

Community
Advanced
cloudflarecloudflare
2.8k

sandbox-stable

Guides building and maintaining Cloudflare Sandbox apps on the stable @cloudflare/sandbox package.

Official
Intermediate