sandbox-stable

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sandbox SDK — stable package

Sandbox SDK — 稳定版包

Isolated Linux environments on Cloudflare Containers, driven from Workers.

Prefer the main Sandbox docs and installed stable types over memory. This skill is a gate, a contract, and a retrieval map—not a full manual.

This line is the current stable default npm package. The main Sandbox documentation describes it. Existing apps can stay here and keep shipping.

We recommend new projects on

@cloudflare/sandbox@next

with sandbox-next
. When you can, plan a move with sandbox-migrate-to-next
so you are ready when 1.0 becomes the stable release. Do not force that port unless the user asks.

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

优先参考Sandbox主文档和已安装的稳定版类型定义，而非依赖记忆。 本技能是一个准入规则、约定和检索指南——而非完整手册。

本行对应当前稳定版默认npm包。主Sandbox文档对其有详细描述。现有应用可继续使用此版本并保持发布。

我们建议新项目使用

@cloudflare/sandbox@next

版本搭配**

sandbox-next

工具。当条件允许时，规划使用

sandbox-migrate-to-next

**进行迁移，以便在1.0版本成为稳定版时做好准备。除非用户明确要求，否则不要强制进行迁移。

1. Gate — confirm the package line

1. 准入规则 — 确认包版本线

Before writing code, inspect the app:

Check	Must match
npm dependency	Default `@cloudflare/sandbox` (not `@next` / preview tags)
Container image	Matching stable image (not `cloudflare/sandbox:next` )

If you find…	Action
`@cloudflare/sandbox@next` or a `next` image	Stop. Load `sandbox-next` .
User wants to port to 1.0 / `@next`	Stop. Load `sandbox-migrate-to-next` . Do not half-apply preview APIs on a stable package.
Only cleaning deprecated stable APIs	Stay here; use the 2026 deprecation guide. That is not a move to `@next` .

Never mix a stable Worker package with an

@next

container image (or the reverse).

Skills install: Agent setup · cloudflare/skills

编写代码前，检查应用：

检查项	必须匹配
npm依赖	默认 `@cloudflare/sandbox` （非 `@next` /预览标签）
容器镜像	匹配的稳定版镜像（非 `cloudflare/sandbox:next` ）

若发现…	操作
`@cloudflare/sandbox@next` 或 `next` 镜像	停止操作。加载 `sandbox-next` 工具。
用户想要迁移至1.0/ `@next` 版本	停止操作。加载 `sandbox-migrate-to-next` 工具。不要在稳定版包上半启用预览版API。
仅清理稳定版已废弃API	继续使用此版本；参考2026废弃指南。这不属于迁移至 `@next` 版本。

永远不要将稳定版Worker包与

@next

容器镜像混合使用（反之亦然）。

技能安装：Agent setup · cloudflare/skills

2. Contract — non-negotiables

2. 约定 — 不可协商规则

```
await sandbox.exec(command)
```
takes a command string and resolves when the command finishes, with buffered
```
stdout
```
/
```
stderr
```
/
```
exitCode
```
(and related fields).
Long-running and streaming work use the stable command APIs (
```
startProcess
```
,
```
execStream
```
, and related helpers)—not the
```
@next
```
single-handle model. Open the Commands docs; do not invent
```
@next
```
```
output()
```
handles on stable.
Sessions can preserve working directory and environment across commands (default session /
```
enableDefaultSession
```
,
```
createSession
```
). See Sessions docs when state must carry across calls.
Interactive browser terminals often use sandbox.terminal(request)
and session/xterm helpers on stable—not preview
```
createTerminal
```
unless the package is
```
@next
```
.
Prefer RPC transport when using tunnels or large/binary streaming. HTTP/WebSocket transports are deprecated (cleanup guide below).
Files, mounts, ports, tunnels, backups, lifecycle, and interpreter: use main docs for signatures; trust installed stable types.
Non-secret config in sandbox env; live credentials in the Worker. Use outbound handlers when processes call external APIs.
Production preview hostnames need wildcard DNS on a custom domain when using those URL patterns.
Do not apply
```
@next
```
argv/
```
process.output()
```
APIs while the dependency is still stable.
Self-deployed bridge stays on the stable package and image. Bridge

Minimal shape:

import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success

```
await sandbox.exec(command)
```
接收命令字符串，在命令完成时返回结果，包含缓冲的
```
stdout
```
/
```
stderr
```
/
```
exitCode
```
（及相关字段）。
长时间运行和流式处理任务使用稳定版命令API（
```
startProcess
```
、
```
execStream
```
及相关辅助方法）——而非
```
@next
```
版本的单句柄模型。请查阅Commands文档，不要在稳定版上自行实现
```
@next
```
的
```
output()
```
句柄。
会话可在多个命令间保留工作目录和环境（默认会话/
```
enableDefaultSession
```
、
```
createSession
```
）。当状态需要跨调用传递时，请查阅Sessions文档。
交互式浏览器终端通常在稳定版上使用**
```
sandbox.terminal(request)
```
**和会话/xterm辅助方法——除非包版本为
```
@next
```
，否则不要使用预览版
```
createTerminal
```
。
使用隧道或大文件/二进制流时，优先选择RPC传输方式。HTTP/WebSocket传输已废弃（清理指南见下文）。
文件、挂载、端口、隧道、备份、生命周期和解释器：参考主文档中的签名；信任已安装的稳定版类型定义。
非敏感配置存储在sandbox环境中；实时凭据存储在Worker中。当进程调用外部API时，使用出站处理程序。
使用特定URL模式时，生产预览主机名需要在自定义域名上配置通配符DNS。
当依赖仍为稳定版时，不要应用
```
@next
```
的argv/
```
process.output()
```
API。
自部署的bridge需保持使用稳定版包和镜像。Bridge

最简示例：

import { getSandbox, proxyToSandbox, Sandbox } from "@cloudflare/sandbox";

export { Sandbox };

const sandbox = getSandbox(env.Sandbox, "user-123");
const result = await sandbox.exec('python3 -c "print(2 + 2)"');
// result.stdout, result.exitCode, result.success

3. Retrieve — open the doc for the task

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

Fetch the page before implementing. Installed stable types win over guesses.

You need to…	Open
Orient	Sandbox overview
First Worker, template, Docker	Get started
`exec` , streaming, background processes	Commands API · Execute commands · Background processes · Streaming output
Sessions / shell state across commands	Sessions concept · Sessions API
`getSandbox` options, sleep, destroy	Lifecycle API · Sandbox options
Env vars	Environment variables
Files	Files API · Manage files · File watching
Buckets / mounts	Storage API · Mount buckets
Backups	Backups API · Backup and restore
Ports, preview URLs, expose	Ports API · Expose services
Tunnels	Tunnels API
Proxy / Workers connections	Proxy requests · Workers connections
Browser / PTY terminal	Terminal API · Terminal concept · Browser terminals
Code interpreter	Interpreter API · Code execution
Git in the sandbox	Git workflows
Secrets / egress	Outbound traffic
WebSockets	WebSocket connections
Docker-in-Docker	Docker in Docker
Production deploy	Production deployment
Containers concept	Containers
How-to index	Guides
API index	API reference
Deprecated APIs while staying on stable	2026 deprecation guide
Self-deployed bridge	Bridge · Bridge HTTP API
Examples (stable/ `main` )	examples on GitHub
New work on 1.0 preview	`sandbox-next` · 1.0 preview
Port existing app to `@next`	`sandbox-migrate-to-next` · Migrate

实现前先查阅对应页面。已安装的稳定版类型定义比猜测更可靠。

你需要…	打开文档
了解概览	Sandbox overview
首个Worker、模板、Docker	Get started
`exec` 、流式处理、后台进程	Commands API · Execute commands · Background processes · Streaming output
会话/跨命令的shell状态	Sessions concept · Sessions API
`getSandbox` 选项、休眠、销毁	Lifecycle API · Sandbox options
环境变量	Environment variables
文件操作	Files API · Manage files · File watching
存储桶/挂载	Storage API · Mount buckets
备份	Backups API · Backup and restore
端口、预览URL、暴露服务	Ports API · Expose services
隧道	Tunnels API
代理/Workers连接	Proxy requests · Workers connections
浏览器/PTY终端	Terminal API · Terminal concept · Browser terminals
代码解释器	Interpreter API · Code execution
Sandbox中的Git	Git workflows
密钥/出站流量	Outbound traffic
WebSockets	WebSocket connections
Docker-in-Docker	Docker in Docker
生产部署	Production deployment
容器概念	Containers
操作指南索引	Guides
API索引	API reference
保持稳定版前提下清理已废弃API	2026 deprecation guide
自部署bridge	Bridge · Bridge HTTP API
示例（稳定版/ `main` 分支）	examples on GitHub
基于1.0预览版的新项目	`sandbox-next` · 1.0 preview
将现有应用迁移至 `@next` 版本	`sandbox-migrate-to-next` · Migrate

Deprecated-API cleanup (stay on stable)

已废弃API清理（保持稳定版）

Update package + matching image first, then follow the guide. Typical search:

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

This path does not switch you to

@next

先更新包和匹配的镜像，再遵循指南操作。典型搜索命令：

rg 'SANDBOX_TRANSPORT|transport:|exposePort\(|enableDefaultSession|execStream\(|readFileStream|writeFileStream'

此操作不会切换至

@next

版本。

4. Before you ship

4. 发布前检查

Worker package and container image on the same stable line
Typecheck against installed stable types
No live secrets in sandbox env
If using deprecated transports/helpers, finish or track 2026 deprecation cleanup
When the team is ready for 1.0, use sandbox-migrate-to-next
—do not force cutover unprompted

Worker包和容器镜像处于同一稳定版版本线
基于已安装的稳定版类型定义进行类型检查
sandbox环境中无实时密钥
若使用已废弃的传输方式/辅助方法，完成或跟踪2026废弃指南中的清理工作
当团队准备好升级至1.0版本时，使用**
```
sandbox-migrate-to-next
```
**——不要在未收到请求的情况下强制切换