AI Agent 变得越来越能干，但有一个问题越来越尖锐：它生成的代码，你敢不敢让它跑？
这是个真实的困境。Agent 帮你写了一段 Python 来清洗数据，代码逻辑看起来没问题，但你不确定 import 的那个包会不会悄悄读你的环境变量，不确定那段 shell 命令是不是真的无害。你当然可以自己先审查一遍再跑，但这样 Agent 帮你省的时间又被审代码吃回去了。
Sandbox SDK 就是冲着这个矛盾来的。它在 Cloudflare Workers 里提供了一个完整的 Linux 容器沙箱，API 只暴露了几个方法：
-
创建沙箱实例 -
执行命令或代码 -
读写文件系统 -
用完直接销毁
你不需要管容器镜像仓库、不需要配网络策略、不需要担心容器逃逸。这些安全边界 Cloudflare 在平台层帮你守住了。
从官方文档和 GitHub 仓库来看，这个 SDK 现在还挂着 Beta 标签。但从它 4300 多个 star 和社区反馈来看，开发者对”安全代码执行做成 API 调用”这件事的需求远比想象中迫切。
这篇文章不会把文档翻译一遍给你看。我会把 Sandbox SDK 的核心设计拆开，重点讲那些文档里写了但你第一遍容易读漏的关键细节，以及几个真正适合用它、和几个目前还不太适合用的场景。如果你在搭 AI Agent 或者任何需要跑不可信代码的产品，看完能帮你少走不少弯路。
环境准备
Sandbox SDK 对本地环境有一个硬性要求，Docker 必须能跑起来。本地开发时 SDK 会起容器来模拟线上沙箱环境，你不需要装虚拟机或者配 Kubernetes，但 docker info 必须能过。
前置条件不算多，但有一个容易被跳过的坑：
| 条件 | 要求 |
|---|---|
| Cloudflare 账号 | Workers Paid 计划（沙箱功能不在免费层） |
| Node.js | 20.x 或更高 |
| Docker | 本地必须可用 |
| Wrangler | npm install -g wrangler |
SDK 本身的安装就一行：
npm install @cloudflare/sandbox
真正要花点时间的不是装包，是配 wrangler.jsonc。你需要在 containers、durable_objects、migrations 三个区块里各声明一次 Sandbox 类。官方给的模板很精确，但如果你之前没配过 Durable Objects，第一次看到这个配置结构会有点懵。它本质上就是把 Sandbox 当成一个 DO 来绑定。
有一点容易被忽略：Docker 本地依赖在国内网络环境下可能多一层问题。如果你拉基础镜像 cloudflare/sandbox:0.7.0 时超时，需要先确认 Docker 的镜像加速器是否配好。这个问题文档里提了但没有强调，建议把它放在排查列表的第一项。
操作流程
Sandbox SDK 的 API 设计有一个很明显的特征：所有能力收进几个方法里，不存在”高级功能需要单独学另一个模块”的情况。获取沙箱实例是所有操作的起点。
sandbox.getSandbox(env.Sandbox, 'session-id') 的第二个参数是隔离标识。同一个 ID 的请求会复用同一个沙箱，不同 ID 完全隔离。这个设计让多租户场景天然就支持了，你不需要自己写一层路由逻辑。
命令执行是最基础的能力，但它做的不是简单的 exec 封装。sandbox.exec('npm test') 返回 stdout、stderr、exitCode 三个字段，同时支持流式输出。如果你需要在 Agent 里实时展示命令运行过程，直接监听 onStdout 回调就行。
# 核心 API 速览
sandbox.exec('command') # 执行命令，返回 { stdout, stderr, exitCode }
sandbox.runCode('code', ctx) # 执行 Python/JS/TS，返回富文本结果
sandbox.writeFile('/path', data) # 写入文件
sandbox.readFile('/path') # 读取文件
sandbox.listFiles('/path') # 列出目录
sandbox.exposePort(8080) # 暴露端口，返回公网 URL
sandbox.gitCheckout('url') # 克隆仓库
代码解释器是这套 API 里最值得细看的部分。runCode() 不是简单地开一个子进程跑 Python，它内建了上下文持久化。你可以在同一个 context 里先 import pandas，再分步查询数据，每一步都能拿到前一步的变量。对于 AI Agent 场景来说，这意味着模型可以分多次执行代码来逐步验证自己，而不是一次性把整个脚本写死然后祈祷它没问题。
有个细节容易被忽略：runCode() 默认支持富文本输出解析。Python 代码画了一张 matplotlib 图，它会自动把图表提取成 PNG 返回给你；DataFrame 会被解析成结构化数据。这个特性让 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，如果你需要额外的系统包，直接在 Dockerfile 里 FROM cloudflare/sandbox:0.7.0 然后 pip install。把”通用能力”和”项目定制”的边界划得很清楚，没有试图做一个万能镜像，这点比很多竞品做得好。
从架构角度看，最值得关注的是沙箱生命周期通过 Durable Objects 来管理。沙箱的存活周期跟 DO 实例同步，这意味着 Worker 处理完请求后如果 DO 还没被回收，沙箱还能继续维持状态。对于需要跨请求保持代码上下文、或者跑长时间后台任务的场景，这个绑定方式很关键。
另外几个近期加入的能力也值得一提：对象存储挂载让沙箱可以直接挂 R2 或 S3 作为本地文件系统，WebSocket 终端接口让前端能直接连到沙箱里的 shell 进程，JWT 代理机制让沙箱可以安全地调用外部 API 而不暴露 Worker 里的真实凭据。
使用场景
AI Agent 代码执行是最直接的场景。假设你的 Agent 被要求”分析这份 CSV 并生成可视化报告”，传统方案要么让用户自己跑代码，要么在你的服务器上跑，两条路都有安全风险。Sandbox SDK 给的是第三条路：Agent 把代码写进沙箱，跑完拿结果，沙箱销毁，全程用户数据和你的服务之间没有直接文件系统接触。
在线代码沙箱是另一个高频场景。用 Sandbox SDK 搭一个类似 Jupyter Notebook 的在线编程环境，用户在浏览器里写 Python，代码在 Worker 里跑，输出通过 WebSocket 实时推回来，还能用 exposePort 起一个临时预览服务。相比于自己搭一套 Kubernetes 集群来隔离用户代码，这个方案的运维成本几乎为零。
但对于 CI/CD 测试隔离这个场景，现在的 Sandbox SDK 还不算最佳选择。虽然它能跑命令、能克隆仓库，但目前每个沙箱的实例数上限是 1（max_instances: 1），意味着同一时间只能有一个测试在跑。需要并行跑多组测试的话，你得自己在上层做任务排队。这个限制大概率会在正式版里放开，但现阶段确实是个硬约束。
数据分析和 notebook 场景倒是一个被低估的使用方向。runCode() 的富文本输出支持和上下文持久化，让它天然适合做”在边缘节点上跑 pandas 查询、返回图表”这种轻量分析任务。不需要把整个 JupyterHub 搬上来，几行 TypeScript 就能搭一个够用的分析接口。
洞察与反思
把 Sandbox SDK 放在 Workers AI 和 Durable Objects 旁边看，Cloudflare 的 AI 基础设施拼图很清楚：Workers AI 负责推理，Durable Objects 负责状态，Sandbox 负责执行。三件套组合起来就是一个从推理到行动的完整 Agent 运行环境。
跟同赛道方案对比：Fly.io Machines 提供了更灵活的容器控制但需要自己管网络层，Modal 的 Python 沙箱在非 Python 场景里受限明显，Replit 的代码执行 API 更像黑盒。Sandbox SDK 的优势在于跟 Cloudflare 全球网络的深度绑定，你不需要考虑”容器跑在哪个区域”这种事。
但现阶段的局限也摆在明面上。Beta 阶段的文档覆盖还不够全，Process API 和 WebSocket 终端相关的示例量太少。定价模型依赖 Containers 的计费方式，对于一个”按需创建、用完即毁”的沙箱场景来说，成本预估不够直观。还有那个 max_instances: 1 的上限，在正式版解决之前，高并发场景需要自己加一层排队逻辑。
从更长的时间维度看，Sandbox SDK 真正在推动的变化是把”安全代码执行”从一个基础设施问题变成一个 API 调用。这件事一旦成为开发者共识，AI Agent 的能力边界会直接外扩。以前因为”不敢让它跑代码”而关掉的能力项，以后可能就只剩一个 sandbox.runCode() 的距离。
资源地址
总结
Sandbox SDK 解决了一个真实问题，而且解决方式很 Cloudflare：用边缘网络的基础设施把复杂度吞掉，露出来的接口简单到只有几个方法。
如果你已经用 Cloudflare Workers 搭 AI 应用，花一个周末把 Sandbox SDK 跑一遍是值得的。不是因为它现在有多完美，是因为它让你摸到了一个趋势：安全代码执行正在从运维层的”怎么隔离”变成应用层的”在哪跑”。
现阶段最值得关注的三个信号：Beta 什么时候摘牌（决定生产可用性），max_instances 上限什么时候放开（决定并发能力），以及定价模型是否会更透明（决定成本预期）。在正式版之前做生产部署的话，建议把沙箱的创建和销毁逻辑单独封装一层，方便后续替换底层实现。