Claude Cursor Skill

sandbox-next

Build or maintain Cloudflare Sandbox apps on @cloudflare/sandbox@next (SDK 1.0 preview). Use sandbox-migrate-to-next when porting a stable app.

LLM Mart · 0 points · 7 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download fcakyon-claude-codex-settings-plugins_cloudflare-skills_skills_sandbox-next-4632eb3.zip · 4 KB
fcakyon/claude-codex-settings 1155 110 forks Apache-2.0 Updated 1d ago
Part of fcakyon/claude-codex-settings — 83 skills

Install

skills CLI npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/cloudflare-skills/skills/sandbox-next
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fcakyon-claude-codex-settings@llmmart
Git git clone https://github.com/fcakyon/claude-codex-settings.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole fcakyon/claude-codex-settings collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Sandbox SDK — @next (1.0 preview)

Isolated Linux environments on Cloudflare 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)

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

Skills install: Agent setup · 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:

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

Task-specific API documentation: references/api-quick-ref.md

Examples index (next branch): 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
First Worker, wrangler, Dockerfile Get started
exec, handles, readiness, durability Process execution
Process API signatures Processes API
Sandbox ID vs container vs sleep/destroy Lifecycle
cwd / env / setEnvVars Environment
Interactive PTY / browser terminal Terminals · Terminals API
Python/JS code interpreter Interpreter · Interpreter API
Extensions model Extensions
Error classes and recovery Errors · Errors API
Common failures Troubleshooting
API hub API reference
Files, mounts, backups, ports, tunnels, proxyToSandbox Main docs for shared surfaces (ignore stable-only session/transport/sandbox.terminal): Files · Storage / mounts · Ports · Tunnels · Backups · Outbound traffic · Expose services · Production
Example apps examples on next
Still on stable package sandbox-stable · Main Sandbox docs
Porting an existing stable app sandbox-migrate-to-next · 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
Files (claude-codex-settings)
  • references
    • api-quick-ref.md 2.4 KB 
      # Sandbox `@next` API documentation

Use this reference after the **sandbox-next** package-line gate. Existing stable apps use **sandbox-stable**; stable-to-preview migrations use **sandbox-migrate-to-next**.

Fetch the page for the task before implementing and check signatures against installed `@cloudflare/sandbox@next` types.

| Task | Documentation |
| --- | --- |
| Launch commands, collect output, stream logs, wait for readiness, inspect or stop processes | [Processes API](https://developers.cloudflare.com/sandbox/1-0-preview/api/processes/) and [Process execution](https://developers.cloudflare.com/sandbox/1-0-preview/processes/) |
| Understand sandbox IDs, container lifetime, sleep, destruction, and durable state | [Sandbox lifecycle](https://developers.cloudflare.com/sandbox/1-0-preview/lifecycle/) |
| Configure sleep, keep-alive, and ID normalization | [Sandbox options](https://developers.cloudflare.com/sandbox/configuration/sandbox-options/); omit removed session and transport fields on `@next`. |
| Create, connect, write to, resize, or stop interactive terminals | [Terminals API](https://developers.cloudflare.com/sandbox/1-0-preview/api/terminals/) and [Terminals](https://developers.cloudflare.com/sandbox/1-0-preview/terminals/) |
| Attach the interpreter, manage contexts, run code, or consume streamed results | [Interpreter](https://developers.cloudflare.com/sandbox/1-0-preview/interpreter/) and [Interpreter API](https://developers.cloudflare.com/sandbox/1-0-preview/api/interpreter/) |
| Set sandbox or per-launch environment | [Environment variables](https://developers.cloudflare.com/sandbox/1-0-preview/environment/) |
| Keep external API credentials in the Worker | [Outbound traffic](https://developers.cloudflare.com/sandbox/guides/outbound-traffic/) |
| Handle startup failures, interrupted work, stale handles, or local wait cancellation | [Errors and recovery](https://developers.cloudflare.com/sandbox/1-0-preview/errors/) and [Errors API](https://developers.cloudflare.com/sandbox/1-0-preview/api/errors/) |
| Find other preview APIs | [Preview API reference](https://developers.cloudflare.com/sandbox/1-0-preview/api/) |

For files, mounts, backups, ports, and tunnels, follow the shared-surface links in the [preview overview](https://developers.cloudflare.com/sandbox/1-0-preview/). Use main-docs signatures only where that overview says they still apply; ignore stable-only session and transport options.
    • examples.md 526 B 
      # `@next` examples index

Pointers only—not a full catalog. Prefer the repo tree and docs.

https://github.com/cloudflare/sandbox-sdk/tree/next/examples

| Example | Use when |
| ------- | -------- |
| `minimal` | Basic `@next` Worker |
| `code-interpreter` | `withInterpreter` |
| `openai-agents` / `opencode` / `claude-code` / `codex` | Agent harnesses |
| `collaborative-terminal` / `s3-mount` | Terminals / mounts |
| `authentication` | Multi-user sandbox IDs |

Use the **`next`** branch for `@cloudflare/sandbox@next`.
  • SKILL.md 6.7 KB 
    ---
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.
license: Apache-2.0
---

# 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
```

Task-specific API documentation: [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

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude