Index of every page on this site: llms.txt
All skills
cloudflare avatar

/sandbox-next

@5108325 official
by cloudflarecloudflare/skills3.4k stars
357
Run it yourself

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

Use this Skill: https://skilld.dev/gh/cloudflare/skills/sandbox-next

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈39 tokens for metadata: the name and description. ≈1.7k when used: this file. ≈1.4k more on demand in 3 files.

Description uses 2.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈158 characters, or 2.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts23d3 checks · Risk SAFE
  • Gen Agent Trust Hub23d

    This skill provides instructions for using the Cloudflare Sandbox SDK preview. It follows security best practices by advising against hardcoding secrets and only references official documentation and repositories from Cloudflare.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

Signed by skilld at 5108325. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 4 weeks ago

README badge

README badge for cloudflare/skills/sandbox-next