sandbox-next

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sandbox SDK —

@next

(1.0 preview)

Sandbox SDK —

@next

（1.0预览版）

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
.

基于Cloudflare Containers构建的隔离Linux环境，由Workers驱动。

优先参考预览版文档和已安装的
@next
类型定义，而非记忆内容。 API会发生变更；本技能是一个入口、一份约定和检索指南——并非完整手册。

我们推荐新项目使用该版本线。仍在使用默认包的应用请使用**

sandbox-stable

。仅在要求时才进行迁移，通过

sandbox-migrate-to-next

**完成。

1. Gate — confirm the package line

1. 入口——确认包版本线

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

编写代码前，检查应用：

检查项	必须匹配
npm依赖	`@cloudflare/sandbox@next` （或其他预览版标签）
容器镜像	同一版本线（例如 `cloudflare/sandbox:next` , `next-python` ）

如果发现…	操作
默认 `@cloudflare/sandbox` （无 `@next` ）	停止。加载 `sandbox-stable` 。请勿使用本技能中的API。
用户希望将稳定版迁移至 `@next`	停止。加载 `sandbox-migrate-to-next` 。
仅自行部署的bridge	Bridge目前尚未纳入1.0预览版版本线。请继续将Bridge与稳定版包和镜像配合使用。Bridge（稳定版）

切勿将

@next

Worker包与稳定版容器镜像混用（反之亦然）。

技能安装：Agent设置 · cloudflare/skills

2. Contract — non-negotiables

2. 约定——不可协商规则

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

Optional non-exhaustive cheatsheet (process/terminal/interpreter only): references/api-quick-ref.md
Examples index (

next

branch): references/examples.md

```
sandbox.exec(argv)
```
接收一个argv列表，并在进程启动时完成解析。它返回一个句柄，而非命令执行完成的结果。

通过句柄方法收集结果：

output()

logs()

waitForExit()

waitForPort()

waitForLog()

kill(signal?)

。

无隐式Shell。Shell语法需要显式指定Shell，例如
```
["/bin/bash", "-lc", script]
```
。
每次启动都是独立的。在一个
```
exec
```
中执行的
```
cd
```
/
```
export
```
对下一个
```
exec
```
不可见。可在每次启动时传入
```
cwd
```
和
```
env
```
，或使用一个Shell脚本。
进程句柄无标准输入。交互式使用请使用终端（
```
createTerminal
```
+
```
connect
```
）。
本地等待的
```
timeout
```
/
```
AbortSignal
```
仅取消等待操作，不会终止进程。请使用
```
kill
```
或
```
exec
```
的远程
```
timeout
```
。
```
getProcess
```
/
```
listProcesses
```
/
```
getTerminal
```
/
```
listTerminals
```
不会启动容器；当无容器运行时，它们会返回
```
null
```
/
```
[]
```
。
进程和终端ID属于当前容器，并非永久绑定到sandbox ID。对于必须在替换后仍能运行的任务，请存储完整的作业信息（argv、cwd、env、应用状态）——而非仅存储ID。
仅将非机密配置放入
```
setEnvVars
```
/启动
```
env
```
中。敏感凭证请保留在Worker中；当sandbox调用外部API时，使用出站处理程序。
请勿使用已移除的稳定版API（核心包中的
```
gitCheckout
```
、字符串形式的
```
exec
```
完成、会话执行、
```
sandbox.terminal(request)
```
）。
请勿对所有错误使用同一重试循环（请参阅错误文档）。

最简示例：

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

可选的非详尽速查表（仅包含进程/终端/解释器）：references/api-quick-ref.md
示例索引（

next

分支）：references/examples.md

3. Retrieve — open the doc for the task

3. 检索——针对任务打开对应文档

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

实现前请查阅对应页面。已安装的

@next

类型定义优先于猜测内容。

你需要…	打开链接
了解概况/选择预览版	1.0预览版概述
首个Worker、wrangler、Dockerfile	快速开始
`exec` 、句柄、就绪状态、持久性	进程执行
进程API签名	进程API
Sandbox ID vs 容器 vs 休眠/销毁	生命周期
`cwd` / `env` / `setEnvVars`	环境配置
交互式PTY/浏览器终端	终端 · 终端API
Python/JS代码解释器	解释器 · 解释器API
扩展模型	扩展
错误类与恢复	错误处理 · 错误API
常见故障	故障排查
API中心	API参考
文件、挂载、备份、端口、隧道、 `proxyToSandbox`	共享功能的主文档（忽略稳定版专属的会话/传输/ `sandbox.terminal` ）：文件 · 存储/挂载 · 端口 · 隧道 · 备份 · 出站流量 · 暴露服务 · 生产部署
示例应用	next分支上的示例
仍在使用稳定版包	`sandbox-stable` · Sandbox主文档
迁移现有稳定版应用	`sandbox-migrate-to-next` · 迁移指南

4. Before you ship

4. 发布前检查

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

Lockfile和Dockerfile使用同一
```
@next
```
版本线
基于已安装的
```
@next
```
类型定义进行类型检查
sandbox环境中无敏感凭证
使用特定URL模式时，生产预览主机名需要在自定义域名上配置通配符DNS

sandbox-next

Original

Translation

Sandbox SDK —
`@next`
(1.0 preview)

Sandbox SDK —
`@next`
（1.0预览版）

1. Gate — confirm the package line

1. 入口——确认包版本线

2. Contract — non-negotiables

2. 约定——不可协商规则

3. Retrieve — open the doc for the task

3. 检索——针对任务打开对应文档

4. Before you ship

4. 发布前检查

sandbox-next

Original

Translation

Sandbox SDK — @next (1.0 preview)

Sandbox SDK — @next（1.0预览版）

1. Gate — confirm the package line

1. 入口——确认包版本线

2. Contract — non-negotiables

2. 约定——不可协商规则

3. Retrieve — open the doc for the task

3. 检索——针对任务打开对应文档

4. Before you ship

4. 发布前检查

Sandbox SDK —
`@next`
(1.0 preview)

Sandbox SDK —
`@next`
（1.0预览版）