AGENT 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.

License 许可
Apache-2.0
所属仓库
filippolmt/skills
最近更新
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

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 / 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

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

filippolmt
filippolmt/skills

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

★ 1
filippolmt
filippolmt/skills

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.

★ 1
filippolmt
filippolmt/skills

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.

★ 1
filippolmt
filippolmt/skills

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.

★ 1
filippolmt
filippolmt/skills

workers-best-practices

Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.

★ 1
filippolmt
filippolmt/skills

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.

★ 1