sandbox-sdk

Cloudflare Sandbox SDK

在 Cloudflare Workers 上构建安全、隔离的代码执行环境。

首先：验证安装

npm install @cloudflare/sandbox
docker info  # Must succeed - Docker required for local dev

检索优先开发

重要：处理 Sandbox SDK 任务时，优先检索文档和示例，而不是依赖预训练知识。

资源	URL
文档	https://developers.cloudflare.com/sandbox/
API 参考	https://developers.cloudflare.com/sandbox/api/
示例	https://github.com/cloudflare/sandbox-sdk/tree/main/examples
入门指南	https://developers.cloudflare.com/sandbox/get-started/

实现功能时，先获取相关文档页面或示例。

必需配置

wrangler.jsonc（必须完全一致，不要修改结构）：

{
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "lite",
    "max_instances": 1
  }],
  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },
  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}

Worker 入口 — 必须重新导出 Sandbox 类：

import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';  // Required export

快速参考

任务	方法
获取沙箱	getSandbox(env.Sandbox, 'user-123')
运行命令	await sandbox.exec('python script.py')
运行代码（解释器）	await sandbox.runCode(code, { language: 'python' })
写入文件	await sandbox.writeFile('/workspace/app.py', content)
读取文件	await sandbox.readFile('/workspace/app.py')
创建目录	await sandbox.mkdir('/workspace/src', { recursive: true })
列出文件	await sandbox.listFiles('/workspace')
暴露端口	await sandbox.exposePort(8080)
销毁	await sandbox.destroy()

核心模式

执行命令

const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python --version');
// result: { stdout, stderr, exitCode, success }

代码解释器（推荐用于 AI）

使用 runCode() 执行大模型生成的代码，并获得丰富的输出：

const ctx = await sandbox.createCodeContext({ language: 'python' });

await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx });
const result = await sandbox.runCode('sum(data)', { context: ctx });
// result.results[0].text = "6"

语言：python、javascript、typescript

状态会在上下文中持续保留。生产环境中请创建显式上下文。

文件操作

await sandbox.mkdir('/workspace/project', { recursive: true });
await sandbox.writeFile('/workspace/project/main.py', code);
const file = await sandbox.readFile('/workspace/project/main.py');
const files = await sandbox.listFiles('/workspace/project');

如何选择

需求	使用	原因
Shell 命令、脚本	exec()	直接控制、流式输出
大模型生成的代码	runCode()	丰富的输出、状态持久化
构建/测试流水线	exec()	退出代码、捕获 stderr
数据分析	runCode()	图表、表格、pandas

扩展 Dockerfile

基础镜像（docker.io/cloudflare/sandbox:0.7.0）包含 Python 3.11、Node.js 20 和常用工具。

通过扩展 Dockerfile 添加依赖：

FROM docker.io/cloudflare/sandbox:0.7.0

# Python packages
RUN pip install requests beautifulsoup4

# Node packages (global)
RUN npm install -g typescript

# System packages
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

EXPOSE 8080  # Required for local dev port exposure

保持镜像精简，以免影响冷启动时间。

预览 URL（端口暴露）

暴露沙箱中运行的 HTTP 服务：

const { url } = await sandbox.exposePort(8080);
// Returns preview URL for the service

生产环境要求：预览 URL 需要配置带有通配符 DNS（*.yourdomain.com）的自定义域名。.workers.dev 域名不支持预览 URL 子域名。

参见：https://developers.cloudflare.com/sandbox/guides/expose-services/

OpenAI Agents SDK 集成

SDK 在 @cloudflare/sandbox/openai 提供了适用于 OpenAI Agents 的辅助工具：

import { Shell, Editor } from '@cloudflare/sandbox/openai';

完整的集成模式请参见 examples/openai-agents。

沙箱生命周期

• getSandbox() 会立即返回，容器会在首次操作时延迟启动
• 容器在闲置 10 分钟后休眠（可通过 sleepAfter 配置）
• 使用 destroy() 可立即释放资源
• 相同的 sandboxId 始终返回同一个沙箱实例

反模式

• 不要使用内部客户端（CommandClient、FileClient）——请使用 sandbox.* 方法
• 不要遗漏 Sandbox 导出——没有 export { Sandbox }，Worker 将无法部署
• 多用户场景下不要硬编码沙箱 ID——请使用用户/会话标识符
• 不要忘记清理——临时沙箱请调用 destroy()

详细参考

• references/api-quick-ref.md — 完整 API，包含选项和返回类型
• references/examples.md — 按使用场景整理的示例索引