cloudflare · ghostwriternr · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
@@ -57,7 +57,9 @@ Skills are contextual and auto-loaded based on your conversation. When a request
 | cloudflare | Comprehensive platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), networking (Tunnel, Spectrum), security (WAF, DDoS), and IaC (Terraform, Pulumi) |
 | agents-sdk | Building stateful AI agents with state, scheduling, RPC, MCP servers, email, and streaming chat |
 | durable-objects | Stateful coordination (chat rooms, games, booking), RPC, SQLite, alarms, WebSockets |
-| sandbox-sdk | Secure code execution for AI code execution, code interpreters, CI/CD systems, and interactive dev environments |
+| sandbox-next | Sandbox on `@cloudflare/sandbox@next` (1.0 preview); recommended for new projects |
+| sandbox-stable | Sandbox on the current stable `@cloudflare/sandbox` package |
+| sandbox-migrate-to-next | Port a stable Sandbox app to `@cloudflare/sandbox@next` |
 | wrangler | Deploying and managing Workers, KV, R2, D1, Vectorize, Queues, Workflows |
 | web-perf | Auditing Core Web Vitals (FCP, LCP, TBT, CLS), render-blocking resources, network chains |
 | building-mcp-server-on-cloudflare | Building remote MCP servers with tools, OAuth, and deployment |

@@ -0,0 +1,185 @@
+---
+name: sandbox-migrate-to-next
+description: Use when porting a Cloudflare Sandbox app from stable @cloudflare/sandbox to @cloudflare/sandbox@next (Sandbox SDK 1.0 preview), or when the user asks to migrate or upgrade to Sandbox 1.0 / @next. Not for day-to-day stable work (sandbox-stable) or new @next apps (sandbox-next).
+---
+
+# Migrate stable → Sandbox SDK 1.0 preview (`@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](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · [1.0 preview](https://developers.cloudflare.com/sandbox/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](https://developers.cloudflare.com/sandbox/guides/2026-deprecation/) 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.**
+
+## 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**  
+
+Stop after any step that needs a user decision.
+
+## 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
+
+| 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](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · after port, day-to-day → **`sandbox-next`**
+
+## Audit
+
+```sh
+rg 'SANDBOX_TRANSPORT|transport:|setTransport|enableDefaultSession|createSession|getSession|deleteSession|execStream\(|startProcess\(|killProcess\(|sandbox\.terminal\(|sessionId|gitCheckout\(|SandboxTransport|ExecutionSession'
+```
+
+Also: string `exec(`, `cd` then a later `exec`, bare `createCodeContext` / `runCode` on `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
+
+```sh
+npm install @cloudflare/sandbox@next
+```
+
+```dockerfile
+FROM cloudflare/sandbox:next
+# Python: cloudflare/sandbox:next-python
+```
+
+Same prerelease tag on Worker and image when not on floating `next`.
+
+### Code by area
+
+Apply replacements from the map. For each area, implement from the doc—not from stable habits:
+
+| Area | Doc |
+| ---- | --- |
+| Commands / handles / waits | [Processes](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) · [Processes API](https://developers.cloudflare.com/sandbox/1-0-preview/api/processes/) |
+| `cwd` / `env` / secrets | [Environment](https://developers.cloudflare.com/sandbox/1-0-preview/environment/) · [Outbound traffic](https://developers.cloudflare.com/sandbox/guides/outbound-traffic/) |
+| Drop sessions | [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · [Lifecycle](https://developers.cloudflare.com/sandbox/1-0-preview/lifecycle/) |
+| Terminals | [Terminals](https://developers.cloudflare.com/sandbox/1-0-preview/terminals/) |
+| Interpreter | [Interpreter](https://developers.cloudflare.com/sandbox/1-0-preview/interpreter/) |
+| Errors | [Errors](https://developers.cloudflare.com/sandbox/1-0-preview/errors/) |
+| Durable job across requests | [Process execution — lifetime / durability](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) |
+
+**Commands (shape):**
+
+```ts
+// 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" });
+```
+
+```ts
+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
+```
+
+**Terminals (shape):**
+
+```ts
+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 });
+```
+
+**Interpreter (shape):**
+
+```ts
+import { Sandbox as BaseSandbox } from "@cloudflare/sandbox";
+import { withInterpreter } from "@cloudflare/sandbox/interpreter";
+
+export class Sandbox extends BaseSandbox<Env> {
+  interpreter = withInterpreter(this);
+}
+```
+
+**Git (shape):**
+
+```ts
+const clone = await sandbox.exec(
+  ["git", "clone", "--depth", "1", "--", repoUrl, "/workspace/repo"],
+  { cwd: "/workspace" },
+);
+const result = await clone.output({ encoding: "utf8" });
+```
+
+Delete transport settings entirely. Remove session APIs. Isolate users with **separate sandbox IDs**.
+
+### Deploy cutover
+
+Staging/branch first. Production is **one** deploy of matching Worker + image:
+
+```sh
+npx wrangler deploy --containers-rollout=immediate
+```
+
+Leave `rollout_active_grace_period` at default `0` (or set `0` if raised). After cutover, pre-deploy process/terminal IDs are invalid. Details: [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) · [Container rollouts](https://developers.cloudflare.com/containers/platform-details/rollouts/)
+
+## 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`  
+
+Then day-to-day work uses **`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`  
@@ -0,0 +1,91 @@
+---
+name: sandbox-next
+description: Use when building or changing Cloudflare Sandbox apps on @cloudflare/sandbox@next (Sandbox SDK 1.0 preview)—code execution, AI runners, interpreters, CI-like jobs, terminals, files, mounts, tunnels, preview URLs, lifecycle, or errors. Not for the default stable package (use sandbox-stable) or for porting stable to @next (use sandbox-migrate-to-next).
+---
+
+# Sandbox SDK — `@next` (1.0 preview)
+
+Isolated Linux environments on [Cloudflare Containers](https://developers.cloudflare.com/containers/), driven from Workers.
+
+**Prefer preview docs and installed `@next` types over memory.** APIs change; this skill is a gate, a contract, and a retrieval map—not a full manual.
+
+We recommend **new projects** on this line. Apps still on the default package use **`sandbox-stable`**. Port only when asked, via **`sandbox-migrate-to-next`**.
+
+## 1. Gate — confirm the package line
+
+Before writing code, inspect the app:
+
+| Check | Must match |
+| ----- | ---------- |
+| npm dependency | `@cloudflare/sandbox@next` (or another preview tag) |
+| Container image | Same line (e.g. `cloudflare/sandbox:next`, `next-python`) |
+
+| If you find… | Action |
+| ------------ | ------ |
+| Default `@cloudflare/sandbox` (no `@next`) | **Stop.** Load **`sandbox-stable`**. Do not apply this skill’s APIs. |
+| User wants to port stable → `@next` | **Stop.** Load **`sandbox-migrate-to-next`**. |
+| Self-deployed **bridge** only | Bridge is **not** on the 1.0 preview line yet. Keep bridge on stable package + image. [Bridge (stable)](https://developers.cloudflare.com/sandbox/bridge/) |
+
+Never mix an `@next` Worker package with a stable container image (or the reverse).
+
+Skills install: [Agent setup](https://developers.cloudflare.com/agent-setup/) · [cloudflare/skills](https://github.com/cloudflare/skills)
+
+## 2. Contract — non-negotiables
+
+- `sandbox.exec(argv)` takes an **argv** list and resolves when the process **starts**. It returns a **handle**, not a finished command result.
+- Collect results with handle methods: `output()`, `logs()`, `waitForExit()`, `waitForPort()`, `waitForLog()`, `kill(signal?)`.
+- No implicit shell. Shell syntax needs an explicit shell, e.g. `["/bin/bash", "-lc", script]`.
+- Each launch is independent. A `cd` / `export` in one `exec` is not visible to the next. Pass `cwd` and `env` per launch, or one shell script.
+- Process handles have **no stdin**. Interactive use → terminals (`createTerminal` + `connect`).
+- Local wait `timeout` / `AbortSignal` cancel the **wait only**. They do not kill the process. Use `kill` or `exec`’s remote `timeout`.
+- `getProcess` / `listProcesses` / `getTerminal` / `listTerminals` do **not** start a container; they return `null` / `[]` when none is up.
+- Process and terminal IDs belong to the **current container**, not forever to a sandbox ID. For work that must survive replace, store the full job (argv, cwd, env, app state)—not only an id.
+- Non-secret config only in `setEnvVars` / launch `env`. Live credentials stay in the Worker; use outbound handlers when the sandbox calls external APIs.
+- Do **not** invent removed stable APIs (`gitCheckout` on core, string-`exec` completion, session execution, `sandbox.terminal(request)`).
+- Do **not** use one retry loop for every error (see Errors docs).
+
+Minimal shape:
+
+```ts
+import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";
+
+export { Sandbox };
+
+const sandbox = getSandbox(env.Sandbox, "user-123");
+const process = await sandbox.exec(["python3", "-c", "print(2 + 2)"]);
+const result = await process.output({ encoding: "utf8" });
+// result.stdout, result.exitCode
+```
+
+Optional **non-exhaustive** cheatsheet (process/terminal/interpreter only): [references/api-quick-ref.md](references/api-quick-ref.md)  
+Examples index (`next` branch): [references/examples.md](references/examples.md)
+
+## 3. Retrieve — open the doc for the task
+
+Fetch the page before implementing. Installed `@next` types win over guesses.
+
+| You need to… | Open |
+| ------------ | ---- |
+| Orient / choose preview | [1.0 preview overview](https://developers.cloudflare.com/sandbox/1-0-preview/) |
+| First Worker, wrangler, Dockerfile | [Get started](https://developers.cloudflare.com/sandbox/1-0-preview/get-started/) |
+| `exec`, handles, readiness, durability | [Process execution](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) |
+| Process API signatures | [Processes API](https://developers.cloudflare.com/sandbox/1-0-preview/api/processes/) |
+| Sandbox ID vs container vs sleep/destroy | [Lifecycle](https://developers.cloudflare.com/sandbox/1-0-preview/lifecycle/) |
+| `cwd` / `env` / `setEnvVars` | [Environment](https://developers.cloudflare.com/sandbox/1-0-preview/environment/) |
+| Interactive PTY / browser terminal | [Terminals](https://developers.cloudflare.com/sandbox/1-0-preview/terminals/) · [Terminals API](https://developers.cloudflare.com/sandbox/1-0-preview/api/terminals/) |
+| Python/JS code interpreter | [Interpreter](https://developers.cloudflare.com/sandbox/1-0-preview/interpreter/) · [Interpreter API](https://developers.cloudflare.com/sandbox/1-0-preview/api/interpreter/) |
+| Extensions model | [Extensions](https://developers.cloudflare.com/sandbox/1-0-preview/extensions/) |
+| Error classes and recovery | [Errors](https://developers.cloudflare.com/sandbox/1-0-preview/errors/) · [Errors API](https://developers.cloudflare.com/sandbox/1-0-preview/api/errors/) |
+| Common failures | [Troubleshooting](https://developers.cloudflare.com/sandbox/1-0-preview/troubleshooting/) |
+| API hub | [API reference](https://developers.cloudflare.com/sandbox/1-0-preview/api/) |
+| Files, mounts, backups, ports, tunnels, `proxyToSandbox` | Main docs for shared surfaces (ignore stable-only session/transport/`sandbox.terminal`): [Files](https://developers.cloudflare.com/sandbox/api/files/) · [Storage / mounts](https://developers.cloudflare.com/sandbox/api/storage/) · [Ports](https://developers.cloudflare.com/sandbox/api/ports/) · [Tunnels](https://developers.cloudflare.com/sandbox/api/tunnels/) · [Backups](https://developers.cloudflare.com/sandbox/api/backups/) · [Outbound traffic](https://developers.cloudflare.com/sandbox/guides/outbound-traffic/) · [Expose services](https://developers.cloudflare.com/sandbox/guides/expose-services/) · [Production](https://developers.cloudflare.com/sandbox/guides/production-deployment/) |
+| Example apps | [examples on `next`](https://github.com/cloudflare/sandbox-sdk/tree/next/examples) |
+| Still on stable package | **`sandbox-stable`** · [Main Sandbox docs](https://developers.cloudflare.com/sandbox/) |
+| Porting an existing stable app | **`sandbox-migrate-to-next`** · [Migrate](https://developers.cloudflare.com/sandbox/1-0-preview/migrate/) |
+
+## 4. Before you ship
+
+- Lockfile and Dockerfile on the **same** `@next` line  
+- Typecheck against installed `@next` types  
+- No live secrets in sandbox env  
+- Production preview hostnames need wildcard DNS on a custom domain when using those URL patterns  
@@ -0,0 +1,94 @@
+# `@next` cheatsheet (not the full API)
+
+Scan aid for the **process / terminal / interpreter** shapes that differ most from stable. **Not exhaustive.**
+
+| For… | Go here |
+| ---- | ------- |
+| Full signatures and types | Installed `@cloudflare/sandbox@next` package types |
+| Preview API hub | https://developers.cloudflare.com/sandbox/1-0-preview/api/ |
+| Processes · terminals · errors · interpreter | Same hub (dedicated pages) |
+| Files, mounts, backups, ports, tunnels, lifecycle options | Main docs linked from the hub and from **`sandbox-next`** § Retrieve — ignore stable-only session/transport bits |
+| Mental model (exec, durability, ID vs container) | https://developers.cloudflare.com/sandbox/1-0-preview/processes/ · https://developers.cloudflare.com/sandbox/1-0-preview/lifecycle/ |
+| `Sandbox` extends `Container` | [Cloudflare Containers](https://developers.cloudflare.com/containers/) + Sandbox lifecycle docs above |
+
+If something is missing here, it is almost certainly **documented elsewhere or in types**—do not invent it from this file.
+
+---
+
+## Lifecycle (common options)
+
+```ts
+getSandbox(binding, sandboxId, options?: {
+  sleepAfter?: string | number;
+  keepAlive?: boolean;
+  normalizeId?: boolean;
+}): Sandbox
+
+await sandbox.destroy(): Promise<void>
+```
+
+No `transport` / `enableDefaultSession` on `@next`.
+
+## Processes
+
+```ts
+await sandbox.exec(argv: readonly [string, ...string[]], options?: {
+  cwd?: string;
+  env?: Record<string, string>;
+  timeout?: number; // remote process lifetime
+}): Promise<SandboxProcess>
+
+await sandbox.getProcess(id: string): Promise<SandboxProcess | null>
+await sandbox.listProcesses(): Promise<ProcessStatus[]>
+
+await process.output({ encoding?: "utf8"; maxBytes?; timeout?; signal? })
+await process.logs({ since?; replay?; follow?; signal? })
+await process.waitForExit({ timeout?; signal? })
+await process.waitForPort(port, { mode?: "tcp" | "http"; path?; timeout?; ... })
+await process.waitForLog(pattern, { stream?; timeout?; signal? })
+await process.kill(signal?: number) // default 15
+await process.status()
+```
+
+`await exec` = launch succeeded, not exit. No process stdin.
+
+## Terminals
+
+```ts
+await sandbox.createTerminal({
+  command: readonly [string, ...string[]];
+  cwd?; env?; cols?; rows?; bufferSize?;
+}): Promise<Terminal>
+
+await sandbox.getTerminal(id): Promise<Terminal | null>
+await sandbox.listTerminals(): Promise<Terminal[]>
+
+await terminal.connect(request, { cursor?; cols?; rows? })
+await terminal.write(data: Uint8Array)
+await terminal.resize(cols, rows)
+await terminal.output({ since?; replay?; follow?; signal? })
+await terminal.interrupt()
+await terminal.terminate()
+```
+
+## Interpreter (extension)
+
+```ts
+import { withInterpreter } from "@cloudflare/sandbox/interpreter";
+// subclass: interpreter = withInterpreter(this)
+
+await sandbox.interpreter.createCodeContext({ language?, cwd? })
+await sandbox.interpreter.runCode(code, { context?, language?, onStdout?, ... })
+await sandbox.interpreter.runCodeStream(code, { context?, language? })
+await sandbox.interpreter.listCodeContexts()
+await sandbox.interpreter.deleteCodeContext(id)
+```
+
+## Environment
+
+```ts
+await sandbox.setEnvVars(Record<string, string | undefined>) // undefined removes
+// plus env on exec / createTerminal
+```
+
+Non-secret config only. Secrets: Worker + outbound handlers.