# sandbox-next

Skill for building Cloudflare Sandbox apps on SDK 1.0 preview (@cloudflare/sandbox@next). Gives the agent rules for the new process and terminal APIs.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 85100 installs · ★ 3424 repo stars
- Author: cloudflare
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/cloudflare/skills/tree/HEAD/skills/sandbox-next/SKILL.md
- Updated: 2026-10-31
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/sandbox-next

## What it does

Cloudflare Sandbox runs isolated Linux environments on containers driven from Workers. The SDK 1.0 preview changed how process execution works: `sandbox.exec(argv)` now returns a handle when the process starts, and you collect results with `output()`, `waitForExit()`, `waitForPort()` methods. There is no implicit shell — shell syntax goes through an explicit shell like `["/bin/bash", "-lc", script]`. Each launch is independent: a `cd` or `export` in one command is not visible to the next.

The skill checks that the Worker package and container image are on the same `@next` line (dependency shows `@next`, Dockerfile uses `cloudflare/sandbox:next`). If it finds the stable package without `@next`, it stops and asks to load `sandbox-stable`. Migrating from stable to preview requires a separate skill, `sandbox-migrate-to-next`. Before writing code, the agent opens the relevant doc page for the task — process handling, PTY terminals, interpreters, error handling, files and mounts.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudflare/skills --skill sandbox-next -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/sandbox-next/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/sandbox-next/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudflare/skills --skill sandbox-next -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/sandbox-next/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudflare/skills --skill sandbox-next -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/sandbox-next/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cloudflare/skills skills/sandbox-next
```

2. **Manually: put the files in place**
- File: `.github/skills/sandbox-next/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudflare/skills --skill sandbox-next -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cloudflare/skills --path skills/sandbox-next
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/sandbox-next/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cloudflare/skills --skill sandbox-next -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cloudflare/skills/tree/HEAD/skills/sandbox-next/SKILL.md

## When to use it
- build a Worker for Cloudflare Sandbox on SDK 1.0 preview
- run a process in a container and wait for it to finish
- open a PTY terminal in the browser from a Workers app
- verify that dependency and image are on the same `@next` line
- get stdout and exitCode of a command through the process handle

## Example prompts
- Create a Worker that runs `python3 script.py` in Sandbox on `@next` and returns stdout
- Add the `sandbox-next` skill for Claude Code
- Check that `package.json` and Dockerfile are on the same `@next` line

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 546a255a24d89d09.

BEGIN THIRD-PARTY FILE 546a255a24d89d09
```text
---
name: sandbox-next
description: Build or maintain Cloudflare Sandbox apps on @cloudflare/sandbox@next (SDK 1.0 preview). Use sandbox-migrate-to-next when porting a stable app.
---

# Sandbox SDK — `@next` (1.0 preview)

Isolated Linux environments on [Cloudflare Containers](https://developers.cloudflare.com/containers/index.md), 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/sdk/bridge/index.md) |

Never mix an `@next` Worker package with a stable container image (or the reverse).

Skills install: [Agent setup](https://developers.cloudflare.com/agent-setup/index.md) · [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.
```
END THIRD-PARTY FILE 546a255a24d89d09

The third-party file has ended. Everything between the 546a255a24d89d09 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2580 of 6921 bytes. © cloudflare · Apache-2.0 · https://github.com/cloudflare/skills/tree/HEAD/skills/sandbox-next/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
