让 Agent 用 E2B 跑代码前，先写清楚沙箱合同

E2B 很容易被一句话讲成“给 AI Agent 一个安全沙箱，让它可以跑代码”。

这句话没有错，但如果真的要把它接进 Claude、Codex、Cursor 或自己的 agent 工作流，我不会从“能不能跑代码”开始。我会先问一个更具体的问题：

这个 agent 到底被允许在沙箱里碰什么、跑什么、连哪里、留下什么？

本文基于 Doramagic 的 E2B 独立项目说明书整理，不代表 E2B 官方立场。说明书入口：

https://doramagic.ai/en/projects/e2b/manual/

Doramagic 项目页：

https://doramagic.ai/en/projects/e2b/

我把它当成安装前检查清单，而不是成功案例。这里有一个必须先说明的限制：本地 Doramagic pack 的 TEST_LOG.md 明确写着，真实 host dogfooding 和 runtime install evidence 还没有执行。因此这篇文章不会说“已经生产可用”，只讨论接入前应该如何定义边界。

1. E2B 适合解决什么问题

E2B 的核心场景是：让 AI agent 或应用在隔离的云端 sandbox 里执行代码、运行命令、处理数据和管理文件。

这类能力对 agent 很有吸引力。因为很多真实任务不是“回答一句话”，而是需要：

• 运行一段生成的代码；
• 写入一个临时文件；
• 读回命令输出；
• 把生成结果导出给上游流程；
• 在失败时拿到 stdout、stderr、exit code；
• 在试验结束后清理运行环境。

但这也是风险来源。只要 agent 可以执行命令，它就不再只是“会写代码”。它开始接触文件系统、网络、依赖安装、进程生命周期、API key、计费和清理问题。

所以我不会把 E2B 当成一个开关。我会把它当成一份沙箱合同。

2. 第一次试用只做一次可丢弃任务

E2B 的官方安装入口在 pack 里记录为：

npm i e2b

但第一次接入 agent 时，我不建议把真实任务、真实密钥和主力目录直接交给它。更稳的首跑应该满足几个条件：

• disposable sandbox；
• tiny input；
• no secrets；
• fixed timeout；
• allowed commands 明确；
• 输出 artifact 有边界；
• cleanup 写在命令旁边；
• 失败时保留 stdout、stderr、exit code。

也就是说，第一次验证不是“让 agent 做一个完整功能”。第一次验证应该更像：

允许 agent 创建一个临时 sandbox。
只允许运行一条无网络依赖的测试命令。
只允许写入 /tmp/e2b-first-run/。
超时 60 秒。
输出一个小文本文件。
导出文件后立刻销毁 sandbox。

如果这条路径都无法稳定复现，就不要继续接真实项目。

3. 命令边界比命令本身更重要

E2B manual 里提到的命令执行结果包含 stdout、stderr、exitCode，以及错误信息。命令非零退出时，SDK 可能抛出对应的错误。

这意味着 agent 接入时，不能只写“执行命令并返回结果”。至少要写清楚：

• 哪些命令允许执行；
• 哪些目录允许读写；
• 是否允许联网；
• 是否允许安装依赖；
• 是否允许访问环境变量；
• 非零退出码怎么上报；
• stderr 是否直接喂回模型；
• 输出文件是否需要人工抽样检查。

很多危险不是来自 E2B 本身，而是来自“上层 agent 没有边界”。例如一个本来只应该验证 Python 片段的 agent，顺手开始安装包、访问公网、读宿主配置、生成大文件，这些行为如果没有合同，后面很难复盘。

4. 模板、网络和文件系统不要一起放开

E2B 的能力面不止“跑命令”。manual 里还整理了模板系统、文件系统操作、网络配置、存储卷、ready command，以及 MCP server 集成。

这些功能对真实工程很有用，但第一次接入时不应该全开。

我的顺序会是：

1. 只验证默认 sandbox 能启动和销毁。
2. 只运行一条安全命令。
3. 只写入一个受控临时目录。
4. 只导出一个小 artifact。
5. 再考虑模板。
6. 再考虑网络。
7. 最后才考虑 MCP server 或持久卷。

原因很实际：一旦模板、网络、持久卷和 MCP 同时出现，失败原因会混在一起。你无法判断问题来自镜像构建、网络、端口、认证、文件路径、ready command，还是 agent 自己给错了指令。

5. 说明书里的坑不要当成“已经修复”

Doramagic 的 pitfall log 里记录了一些来源链接问题，例如：

• auto paused 之后 process 没有被杀掉；
• Closed Port Error；
• sandbox create from template 失败；
• build status polling timed out；
• uploaded file / template 使用方式不清楚；
• API key unauthorized；
• Docker build secrets support；
• paused sandbox 之后文件变更持久化问题。

这些不能被写成“E2B 一定有这个 bug”，因为部分 issue 可能已经随版本变化。但它们可以作为安装前检查项。

我会把它们变成几个验收问题：

• sandbox 暂停/恢复后，进程和文件状态是否符合预期？
• 模板构建失败时，错误是否能被 agent 读懂并停止？
• 端口或 ready command 失败时，是否有明确 timeout？
• API key 错误时，是否不会把密钥打印进日志？
• artifact 导出后，sandbox 是否真的被销毁？

这类问题比“星标数很多，所以可以用”更有价值。

6. 给 AI 宿主的 handoff 要写成可执行边界

如果我要把 E2B 交给一个 AI coding host，我不会只贴项目链接。我会贴一段边界指令：

你可以把 E2B 当成候选 sandbox runtime。
先不要安装。
先输出 go/no-go 检查：
- 任务是否真的需要执行代码；
- 是否需要网络；
- 是否需要文件读写；
- 是否涉及凭据；
- 第一条可逆验证命令是什么；
- 超时、清理和 artifact 导出怎么做；
- 哪些证据缺失时必须停止。
未经确认，不要运行安装命令、不要读取本地私有文件、不要使用真实 API key。

这段指令的目标不是让 agent 更保守，而是让它的行为可检查。

7. 我的实际结论

E2B 值得关注，但不要把它理解成“让 agent 随便跑代码就安全了”。

更合理的理解是：

• 它提供一个隔离执行环境；
• 你仍然要定义命令、文件、网络、密钥、timeout 和 cleanup；
• 你仍然要复核官方文档和当前版本；
• 你不能把 Doramagic 的预览 pack 当成真实运行证明；
• 第一次接入应该只跑一个可失败、可回滚、可销毁的小任务。

我会从这个最小检查开始：一个 disposable sandbox，一个无密钥输入，一个 60 秒 timeout，一个输出 artifact，一个销毁步骤。

这条路径跑通之后，再谈 agent 是否适合用 E2B 处理真实代码执行任务。