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 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- 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 资源文件 3
- 参考文档references/api-quick-ref.md2.3 KB
- 参考文档references/examples.md526 B
- 参考文档references/skill-feedback.md2.7 KB
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.
workflow-modernize
パッケージ/CLI更新時や定期見直し時に、自作スキル・ワークフロー・設定を監査し、不要なworkaroundの撤廃・新機能の適用・プロンプトの簡素化をGrill(壁打ち)と多角比較で提案・修正する。「workflow-modernize」「スキル監査」「ワークフロー改善」「パッケージ更新後の見直し」「モダナイズ」で起動。
workers-best-practices
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
web-perf
Audit, diagnose, or optimize website loading and interaction performance, Core Web Vitals, and Lighthouse performance scores.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.