sandbox-migrate-to-next

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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/sdk/migrate/index.md) · [1.0 preview](https://developers.cloudflare.com/sandbox/index.md)

**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/sdk/migrate/index.md) 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/sdk/migrate/index.md) · 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/index.md) · [Processes API](https://developers.cloudflare.com/sandbox/index.md) |
| `cwd` / `env` / secrets | [Environment](https://developers.cloudflare.com/sandbox/index.md) · [Outbound traffic](https://developers.cloudflare.com/sandbox/sdk/guides/outbound-traffic/index.md) |
| Drop sessions | [Migrate](https://developers.cloudflare.com/sandbox/sdk/migrate/index.md) · [Lifecycle](https://developers.cloudflare.com/sandbox/index.md) |
| Terminals | [Terminals](https://developers.cloudflare.com/sandbox/index.md) |
| Interpreter | [Interpreter](https://developers.cloudflare.com/sandbox/index.md) |
| Errors | [Errors](https://developers.cloudflare.com/sandbox/index.md) |
| Durable job across requests | [Process execution — lifetime / durability](https://developers.cloudflare.com/sandbox/index.md) |

**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);

From cloudflare/skills, Apache-2.0.

More from cloudflare/skills