Yolobox：AI 代理的安全沙箱方案

██╗   ██╗ ██████╗ ██╗      ██████╗ ██████╗  ██████╗ ██╗  ██╗
╚██╗ ██╔╝██╔═══██╗██║     ██╔═══██╗██╔══██╗██╔═══██╗╚██╗██╔╝
 ╚████╔╝ ██║   ██║██║     ██║   ██║██████╔╝██║   ██║ ╚███╔╝
  ╚██╔╝  ██║   ██║██║     ██║   ██║██╔══██╗██║   ██║ ██╔██╗
   ██║   ╚██████╔╝███████╗╚██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗
   ╚═╝    ╚═════╝ ╚══════╝ ╚═════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

让你的 AI 放开手脚，全力开干。你的主目录依然安然无恙。

更新日志：CHANGELOG.md

以「yolo mode」运行 Claude Code、Codex、Kimi Code、Gemini、Antigravity、OpenCode、Copilot、Pi 或任何 AI coding agent，同时不用担心主目录被一锅端。

当你允许 AI coding agent 无需询问权限便可执行命令时，它们的能力强得惊人。但只要它误解了一次 prompt，再来一条 rm -rf ~，你就得从备份中恢复了（说得好像你真有备份似的，笑死）。

yolobox 会在容器中运行你的 AI agent，其中：

• 项目目录会挂载到它的真实路径，例如 /Users/you/project

• agent 在容器内拥有完整权限和 sudo

• 除非你明确选择加入，否则不会挂载你的主目录

• 持久化卷会跨多次运行保留工具、配置和会话

• Claude、Codex 和 Kimi Code 内置了 yolobox 使用指南，因此能够理解自己所处的 sandbox

AI 可以在 sandbox 里彻底放飞自我。至于你真正的主目录？它碰都碰不到。

# Install via Homebrew
brew install finbarr/tap/yolobox

# Or install via script
curl -fsSL https://raw.githubusercontent.com/finbarr/yolobox/master/install.sh | bash

然后在任意项目中运行：

cd /path/to/your/project
yolobox claude    # Let it rip

其他 AI 快捷命令的用法也一样：

yolobox codex
yolobox gemini
yolobox kimi
yolobox agy
yolobox antigravity
yolobox opencode
yolobox copilot
yolobox pi

设置 default_harness = "codex"，直接运行 yolobox 时便会启动 Codex。如果想进入手动 shell，请使用 yolobox shell；如果只想在 sandbox 中执行一条命令，请使用 yolobox run <cmd...>。

完整的安装和运行时说明位于 Installation & Setup，命令示例位于 Commands。

基础镜像包含 AI CLI、Node.js、Python、Go、Bun、构建工具、Git、GitHub CLI、ripgrep、fd、fzf、jq、vim、RTK，以及其他常用的实用工具。

还需要别的东西？agent 有 sudo。

在 yolobox 内，受支持的 AI CLI 都经过了封装，会跳过权限提示。没有确认，没有护栏，只有自然法则所期望的、纯粹且不受过滤的 AI。

有关完整工具列表、YOLO-mode 封装器表格、RTK 说明、npm package 新鲜度策略，以及内置 CLI 的升级行为，请参阅 What's in the Box。

项目自定义

如果某个项目需要额外的工具或环境变量，可以添加一份精简的项目配置，无需 fork 整个基础镜像：

# .yolobox.toml
env = ["CODEX_HOME=/home/yolo/.codex-account"]

[customize]
packages = ["default-jdk", "maven"]

yolobox run mvn --version

项目级自定义还可以在基础镜像之上叠加一个 Dockerfile 片段。首次运行时会构建派生镜像；后续运行将复用该镜像，直到基础镜像或自定义输入发生变化。

环境变量值请使用容器内路径，因为这些值会直接传递给 yolobox 内部的进程。env 的值会原样传给运行时，其中的任何内容都不会被解释。

如果希望同名变量在 sandbox 中使用不同于 host 的值——例如传入一个只读 token，而不是你真正使用的 token——可以通过 env_from_host（或 --env-from-host KEY=HOST_VAR）为它设置别名：

# .yolobox.toml
env_from_host = ["GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN"]

这个别名会接管该变量：它会阻止同一 key 的自动透传和 --gh-token；如果 host 变量未设置，yolobox 会拒绝启动，从而确保被它替代的 token 绝不会意外泄漏进去。

有关项目环境变量设置，请参阅 Configuration；有关 package 安装、Dockerfile 片段、重新构建行为、升级行为和完全自定义镜像，请参阅 Project-Level Customization。

yolobox setup                         # Configure global defaults
yolobox config                        # Show resolved config for this project
yolobox claude --docker --gh-token    # Give the agent Docker and GitHub access
yolobox codex --rtk                   # Enable RTK command-output compression
yolobox run --no-network make test    # Run one command with no network
yolobox fork --name bruno codex       # Give an agent its own project copy
yolobox upgrade                       # Update binary and pull the latest image
yolobox update-agents                 # Update AI CLIs in the persistent box

详细参考资料特意集中放在文档站点中：

• Commands：快捷命令、维护命令、fork 和示例

• Configuration：全局配置、项目配置、复制的指令、环境变量透传和上下文清单

• Flags：所有 flag、兼容性说明和运行时透传细节

• Recipes：并行 agent 和 Web 应用路由

理念：这是 AI 的 Box，不是你的

yolobox 是为 AI agent 设计的，不是为人类设计的。你只需启动 AI，然后放手让它工作。

agent 在容器内拥有 sudo。如果它需要编译器、数据库、package 或 framework，自己安装即可。命名卷会跨会话保留这些配置，因此你不必把 README 变成一份长达上百行的 package 矩阵。把它指向你的项目，让它开干就好。

yolobox 用来防范意外事故，并不是什么能从理论上杜绝容器逃逸的神奇定理。

它有助于保护你的主目录、SSH key、dotfile、无关项目，以及 host 文件系统中的大部分状态，使其免受粗心的破坏性命令影响。但它无法保护你挂载的项目目录、明确转发的 secret、明确桥接到 host 的操作，也无法保护 host kernel 免受运行时逃逸漏洞的攻击。

如需更严格的隔离，可以组合使用以下 flag：

yolobox claude --no-network --no-env-passthrough --readonly-project --exclude ".env*" --exclude "secrets/**"

如果你担心的是恶意代码，而非粗心代码，请使用更强的隔离方案，例如 rootless Podman 或 VM。完整的威胁模型和加固选项位于 Security Model。

make build
make test
make lint
make image

贡献者工作流、文档站点命令、版本管理和发布规则位于 Contributing。