你有没有遇到过这种情况，Agent 很聪明地帮你写了一段 Python，你看着代码逻辑没问题，但你不敢让它跑。不是不相信 AI，是不相信 AI 生成的代码不会在服务器上搞出点什么意外。
这就是 Sandbox SDK 要解决的核心矛盾。AI 需要执行代码来完成任务，但你不想给它 root 权限。Cloudflare 的方案是把”不受信任的代码执行”这件事做成了一个 SDK，让你在 Worker 里就能起一个隔离容器，跑完就销毁，全程跟你自己的基础设施零接触。
从文档和 GitHub 仓库来看，这个 SDK 目前还挂着 Beta 标签，但已经有 4300 多个 star。它挂在 Cloudflare Containers 上，本质上是一个 Worker 原生的隔离执行原语。你不需要自己管理 VM、不需要配 Docker 网络、不需要担心容器逃逸，因为这些安全边界 Cloudflare 帮你守住了。
说真的，这篇文章不打算把官方文档翻译一遍给你看。我就是把 Sandbox SDK 的核心能力拆开看了看，哪些地方设计得聪明，哪些地方目前还差点意思，实际用的时候大概会踩哪些坑。如果你正在搭 AI Agent 或者代码执行类的产品，看完应该能省不少调研时间。
环境准备
Sandbox SDK 对本地开发环境有一个硬性要求，Docker 必须能跑起来。因为本地测试时 SDK 会起容器来模拟线上沙箱环境。
前置条件不算复杂，但有一个容易被忽略的点：
| 条件 | 要求 |
|---|---|
| Cloudflare 账号 | Workers Paid 计划（沙箱功能不免费） |
| Node.js | 20.x 或更高 |
| Docker | 本地必须可用，docker info 能通过 |
| Wrangler | npm install -g wrangler |
安装 SDK 本身只有一行命令：
npm install @cloudflare/sandbox
真正需要花点时间的不是装包，是配 wrangler.jsonc。你需要在 containers、durable_objects、migrations 三个区块里各声明一次 Sandbox 类。官方给的配置模板很精确，但结构上用的是 Durable Objects 那一套绑定方式，如果你之前没配过 DO，第一次看到会有点懵。
验证环境是否就绪的最好方式不是跑 wrangler dev，而是先检查 Docker 是否真的在运行。我自己遇到过两次卡在启动阶段，最后发现是 Docker Desktop 没起来。官方文档里提到了这步但没有强调，个人建议把它放在检查列表第一项。
操作流程
Sandbox SDK 的 API 设计有一个很明显的特点，它把所有能力收进了几个方法里，不存在”高级功能需要单独学另一个模块”的情况。
获取沙箱实例是所有操作的起点。getSandbox(env.Sandbox, 'session-id') 里第二个参数是隔离标识，同一个 ID 的请求会复用同一个沙箱，不同 ID 完全隔离。这个设计让多租户场景天然就支持了。
命令执行是最基础的能力。sandbox.exec('npm test') 会返回 stdout、stderr、exitCode 三个字段，同时支持流式输出。如果你需要在 Agent 里实时展示命令执行过程，直接监听 onStdout 回调就行。相比于自己搭 Docker API 的那套流程，这个接口的复杂度降了一个数量级。
# 核心 API 速览
sandbox.exec('command') # 执行命令，返回 { stdout, stderr, exitCode }
sandbox.runCode('code', ctx) # 执行 Python/JS/TS 代码，返回富文本输出
sandbox.writeFile('/path', data) # 写入文件
sandbox.readFile('/path') # 读取文件
sandbox.exposePort(8080) # 暴露端口，返回公网 URL
sandbox.gitCheckout('url') # 克隆仓库
代码解释器是这套 API 里最让我意外的部分。runCode() 不是简单地 exec 一个 Python 文件，它内建了上下文持久化。你可以在同一个 context 里先 import pandas，再分步查询数据，每一步都能拿到前一步的变量。对于 AI Agent 场景来说，这意味着模型可以分多次执行代码来逐步验证自己的想法，而不是一次性把整个脚本写死。
有个容易被忽略的细节：runCode() 默认支持富文本输出解析。如果你的 Python 代码画了一张 matplotlib 图，它会自动把图表提取成 PNG 返回给你，表格会被解析成结构化数据。这个特性让 Agent 写数据可视化代码的体验直接从”给用户看终端日志”升级到了”给用户看图”。
关键设计
Sandbox SDK 最核心的设计决策，是它没有走”给 Worker 加一个 exec 函数”的轻量路线，而是在 Worker 和容器之间架了一层完整的沙箱抽象。
这种设计意味着每个沙箱都是一个完整的 Linux 容器，而不是任何形式的轻量模拟：
-
不是 chroot 文件系统隔离 -
不是 Linux namespace 进程隔离 -
不是 WebAssembly 模拟的”类容器”环境
好处很明显：你可以在里面跑 Node.js 和 Python 这些主流解释型语言，也可以跑编译型语言，甚至可以起一个数据库进程。坏处是冷启动时间比 WASM 方案要长，官方数据是”毫秒级”，但从社区反馈来看，首次启动通常需要 1 到 3 秒。对于需要快速响应的交互式场景，这个延迟可能会影响体验，但放在 AI Agent 执行代码的上下文里基本可以接受。
另一个巧妙的设计是 Dockerfile 扩展机制。基础镜像 cloudflare/sandbox:0.7.0 只带了 Python 3.11 和 Node.js 20，如果你需要额外的系统包或 Python 库，直接在 Dockerfile 里 FROM cloudflare/sandbox:0.7.0 然后 pip install 就行。这个设计把”通用能力”和”项目定制”的边界划得很清楚，没有试图做一个万能镜像。
从架构角度看，最值得关注的是沙箱生命周期和 Worker 生命周期的绑定方式。通过 Durable Objects 来管理沙箱状态，沙箱的存活周期跟 DO 实例同步。这意味着如果你的 Worker 处理完请求后 DO 还没被回收，沙箱还能继续保持状态，对于需要跨请求保持代码上下文的场景非常关键。
使用场景
先说最直接的场景：AI Agent 代码执行。假设你的 Agent 被要求”分析这份 CSV 并生成可视化报告”，传统方案要么让用户自己跑代码，要么在你的服务器上跑，两条路都不理想。Sandbox SDK 提供的是第三条路：Agent 把代码写进沙箱，跑完拿到结果，沙箱销毁，全程用户数据和你的服务之间没有直接文件系统接触。
在线代码沙箱是另一个高频场景。用 Sandbox SDK 搭一个类似 Jupyter Notebook 的在线编程环境，用户可以在浏览器里写 Python，代码在 Worker 里跑，输出通过 WebSocket 实时推回来，还能用 exposePort 起一个临时预览服务。相比于自己搭一套 Kubernetes 集群来隔离用户代码，这个方案的运维成本几乎为零，对于小团队或者独立开发者来说是降维打击级别的简化。
CI/CD 测试隔离这个场景反而不太适合现在的 Sandbox SDK。虽然它能跑命令、能克隆仓库，但目前每个沙箱的实例数上限是 1（max_instances: 1），意味着同一时间只能有一个测试在跑。对于需要并行跑多组测试的场景，你需要自己在上层做任务排队。这个限制大概率会在正式版里放开，但现阶段确实是一个硬伤。
洞察与反思
Cloudflare 做 Sandbox SDK 的意图远比”提供一个工具”要大。把它放在 Workers AI 和 Durable Objects 旁边看，你会发现一个完整的 AI 基础设施拼图正在成型：Workers AI 负责推理，Durable Objects 负责状态，Sandbox 负责执行。三件套组合起来，就是一个从推理到行动的完整 Agent 运行环境。
跟同赛道的方案对比，Fly.io Machines 提供了更灵活的容器控制但需要自己管理网络层，Modal 的 Python 沙箱体验流畅但在非 Python 场景里受限明显，Replit 的代码执行 API 更像黑盒。Sandbox SDK 的优势在于它跟 Cloudflare 的全球网络深度绑定，你不需要考虑”容器跑在哪个区域”这种问题。
但现阶段的局限也很明显。Beta 阶段的文档覆盖不够全，Process API 和 WebSocket 相关的示例严重不足。定价模型目前依赖 Containers 的计费方式，对于一个”按需创建、用完即毁”的沙箱场景来说，成本预估不太直观。另外 Docker 本地依赖在 Windows 上的体验还不够顺畅，对国内开发者来说多了一层网络问题。
从更长的时间维度看，Sandbox SDK 最大的价值可能不在工具本身，而在于它把”安全代码执行”从一个基础设施问题变成了一个 API 调用。这件事一旦成为开发者共识，AI Agent 的能力边界会往外扩一大圈。
资源地址
总结
Sandbox SDK 解决了一个真实存在的问题，而且解决方式很 Cloudflare：用边缘网络的基础设施把复杂度包进去，露出来的接口简单到只有几个方法。如果你是 AI Agent 开发者，这个 SDK 应该是你工具箱里的第一梯队候选。
现在最值得关注的是它什么时候摘掉 Beta 标签。正式版出来之后，实例数上限、冷启动优化、定价透明度这几个问题大概率会有一个更确定的答案。在正式版之前用它做生产环境的话，建议把沙箱的创建和销毁逻辑单独封装一层，方便后续替换。
如果你已经在用 Cloudflare Workers 搭 AI 应用，Sandbox SDK 值得花一个周末跑一遍。不是因为它现在有多完美，是因为它能让你提前看到一个趋势：安全代码执行正在从基础设施层的运维问题变成应用层的一个函数调用。