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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- 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.
02 资源文件 5
- 许可证LICENSE11.1 KB
- 参考文档references/api-quick-ref.md2.3 KB
- 参考文档references/examples.md526 B
- 参考文档references/skill-feedback.md2.7 KB
- 参考文档SOURCE.md396 B
03 SKILL.md 正文
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/exportin oneexecis not visible to the next. Passcwdandenvper launch, or one shell script. - Process handles have no stdin. Interactive use → terminals (
createTerminal+connect). - Local wait
timeout/AbortSignalcancel the wait only. They do not kill the process. Usekillorexec’s remotetimeout. getProcess/listProcesses/getTerminal/listTerminalsdo not start a container; they returnnull/[]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/ launchenv. Live credentials stay in the Worker; use outbound handlers when the sandbox calls external APIs. - Do not invent removed stable APIs (
gitCheckouton core, string-execcompletion, 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
@nextline - Typecheck against installed
@nexttypes - No live secrets in sandbox env
- Production preview hostnames need wildcard DNS on a custom domain when using those URL patterns
Skill feedback
If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.
04 同仓库更多 Skills
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wrangler
Run or troubleshoot Wrangler CLI commands in projects that have a wrangler.jsonc, wrangler.json, or wrangler.toml file, including local development, Previews, deployment, and resource management. For new projects and projects without a Wrangler configuration file, use the cf CLI instead.
workers-profiling
Profile or debug CPU usage and memory allocation in deployed Cloudflare Workers and Durable Objects. Then use this information to optimize your code.
workers-development
Run, inspect, and debug Cloudflare Workers during local development with cf dev, wrangler dev, or the Cloudflare Vite plugin, using Local Explorer to read and seed binding data and query local traces and logs. Also routes production debugging to Workers observability. Use for debugging requests whether or not the project uses Wrangler.
workers-best-practices
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
wordpress-pro
Develops custom WordPress themes and plugins, creates and registers Gutenberg blocks and block patterns, configures WooCommerce stores, implements WordPress REST API endpoints, applies security hardening (nonces, sanitization, escaping, capability checks), and optimizes performance through caching and query tuning. Use when building WordPress themes, writing plugins, customizing Gutenberg blocks, extending WooCommerce, working with ACF, using the WordPress REST API, applying hooks and filters, or improving WordPress performance and security.