Zerobox：隔离运行命令的沙箱工具

对任意命令进行沙箱隔离，并控制文件、网络和凭据访问。

这是一款由 OpenAI Codex 沙箱运行时驱动的轻量级、跨平台进程沙箱工具。

默认拒绝：除非明确允许，否则禁止写入、网络访问和读取环境变量。

凭据注入：传入进程永远无法看到的 API key。Zerobox 只会为获准访问的主机注入真实值。

文件访问控制：允许或拒绝读取及写入指定路径。

网络过滤：按域名允许或拒绝出站流量。

干净的环境：默认只继承必要的环境变量，例如 PATH、HOME 等。

提供 Rust、TypeScript 和 Python SDK，并在不同语言中保持一致的 API。

跨平台：支持 macOS 和 Linux，已规划支持 Windows。

单个二进制文件：不需要 Docker，不需要 VM，额外开销约为 10ms。

运行命令，同时禁止写入和网络访问：

zerobox -- node -e "console.log('hello')"

允许写入指定目录：

zerobox --allow-write=. -- node script.js

允许访问指定网络域名：

zerobox --allow-net=api.openai.com -- node agent.js

将 secret 传递给指定主机，而内部进程永远看不到真实值：

zerobox --secret OPENAI_API_KEY=sk-proj-123 --secret-host OPENAI_API_KEY=api.openai.com -- node agent.js

记录文件系统变更，并在执行结束后撤销：

zerobox --restore --allow-write=. -- npm install

或者只记录而不恢复，之后再检查并撤销：

zerobox --snapshot --allow-write=. -- npm install
zerobox snapshot list
zerobox snapshot diff <session-id>
zerobox snapshot restore <session-id>

如需以编程方式使用，请直接查看与你的技术栈匹配的 SDK。

Secret 是 API key、token 或凭据，绝不应该暴露在沙箱内部。沙箱中的进程会在环境变量里看到一个占位符；只有向指定主机发起网络请求时，网络代理层才会将其替换为真实值。

sandbox process: echo $OPENAI_API_KEY
  -> ZEROBOX_SECRET_a1b2c3d4e5...  (placeholder)

sandbox process: curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/...
  -> proxy intercepts, replaces placeholder with real key
  -> server receives: Authorization: Bearer sk-proj-123

使用 --secret 传入 secret，并通过 --secret-host 将其限制在指定域名：

zerobox --secret OPENAI_API_KEY=sk-proj-123 --secret-host OPENAI_API_KEY=api.openai.com -- node app.js

如果不指定 --secret-host，secret 将被传递给所有域名：

zerobox --secret TOKEN=abc123 -- node app.js

为多个 secret 分别配置不同的主机：

zerobox \
  --secret OPENAI_API_KEY=sk-proj-123 --secret-host OPENAI_API_KEY=api.openai.com \
  --secret GITHUB_TOKEN=ghp-456 --secret-host GITHUB_TOKEN=api.github.com \
  -- node app.js

Node.js 的 fetch 默认不遵循 HTTPS_PROXY。在沙箱内运行使用 secret 的 Node.js 时，请务必传入 --use-env-proxy 参数。

SDK 代码示例请参阅 Rust、TypeScript 或 Python README。

环境变量

默认情况下，只会向沙箱传递必要的变量，例如 PATH、HOME、USER、SHELL、TERM 和 LANG。

继承父进程的所有环境变量：

zerobox --allow-env -- node app.js

只继承指定的环境变量：

zerobox --allow-env=PATH,HOME,DATABASE_URL -- node app.js

阻止指定的环境变量：

zerobox --allow-env --deny-env=AWS_SECRET_ACCESS_KEY -- node app.js

或者显式设置变量：

zerobox --env NODE_ENV=production --env DEBUG=false -- node app.js

安全运行 AI 生成的代码

运行 AI 生成的代码，同时避免文件损坏或数据泄露风险：

zerobox -- python3 /tmp/task.py

或者只允许写入输出目录：

zerobox --allow-write=/tmp/output -- python3 /tmp/task.py

限制 LLM 工具调用

可以分别对每次 AI 工具调用进行沙箱隔离。父级 Agent 进程照常运行，只有部分操作会进入沙箱。完整的可运行示例包括：

examples/ai-agent-sandboxed：用带有 secret 的沙箱封装整个 Agent 进程，使 API key 始终不可见。

examples/ai-agent：使用 Vercel AI SDK，实现按工具调用进行沙箱隔离并注入 secret。

examples/workflow：运行 Vercel Workflow，并将持久化步骤置于沙箱中。

在构建期间保护代码仓库

运行构建，允许网络访问，但将写入范围限制在 ./dist：

zerobox --allow-write=./dist --allow-net -- npm run build

运行测试时禁止网络访问，并捕获意外的外部调用：

zerobox --allow-write=/tmp -- npm test

沙箱的额外开销很低，通常约为 10ms 和 7MB：

数据来自 Apple M5 Pro 上预热后的 10 次运行最佳结果。运行 ./bench/run.sh 即可复现。