██╗ ██╗ ██████╗ ██╗ ██████╗ ██████╗ ██████╗ ██╗ ██╗
╚██╗ ██╔╝██╔═══██╗██║ ██╔═══██╗██╔══██╗██╔═══██╗╚██╗██╔╝
╚████╔╝ ██║ ██║██║ ██║ ██║██████╔╝██║ ██║ ╚███╔╝
╚██╔╝ ██║ ██║██║ ██║ ██║██╔══██╗██║ ██║ ██╔██╗
██║ ╚██████╔╝███████╗╚██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗
╚═╝ ╚═════╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝
让你的 AI 全力运行。你的主目录依然安然无恙。
文档:yolobox.dev
更新日志:CHANGELOG.md
在“yolo 模式”下运行 Claude Code、Codex、Kimi Code、Gemini、Antigravity、OpenCode、Copilot、Pi 或任何 AI 编码代理,而不会毁掉你的主目录。
当你允许 AI 编码代理无需请求许可即可运行命令时,它们会变得极其强大。但只要一次提示被误解,紧接着就是 rm -rf ~,之后你只能从备份中恢复(得了吧,说得好像你有备份一样,哈哈)。
yolobox 会在容器内运行你的 AI 代理,其中:
/Users/you/projectAI 可以在沙箱内完全肆意妄为。而你真正的主目录?不可触碰。
# Install via Homebrew
brew install finbarr/tap/yolobox
# Or install via script
curl -fsSL https://raw.githubusercontent.com/finbarr/yolobox/master/install.sh | bash
Homebrew 会自动安装 bash 和 zsh 补全。对于脚本安装方式,请参阅 shell completions。
然后在任意项目中:
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,需要在沙箱中执行单条命令时使用 yolobox run <cmd...>。
基础镜像自带 AI CLI、Codex 和 Claude ACP 适配器、Node.js、Python、Go、Bun、构建工具、Git、GitHub CLI、ripgrep、fd、fzf、jq、vim、RTK,以及常见的实用工具。
还需要别的?Agent 拥有 sudo 权限。
在 yolobox 内部,受支持的 AI CLI 会被包装以跳过权限提示。没有确认,没有护栏。只有纯粹未经过滤的 AI,正如自然所愿。
对于 ACP 客户端或编辑器,使用 yolobox run codex-acp 或 yolobox run claude-agent-acp 作为其 stdio agent 命令。这些适配器捆绑了兼容的引擎,并使用客户端的权限模式;yolobox 的 CLI YOLO 包装器和 --no-yolo 不会控制它们。现有的配置同步和认证选项仍然适用。启动示例见 ACP 客户端。
镜像拉取和自定义镜像构建进度输出到 stderr,将 stdout 和管道 stdin 留给容器命令,包括在 ACP 启动期间。
完整的工具列表、YOLO 模式包装器表、RTK 说明、npm 包新鲜度策略以及捆绑 CLI 升级行为,见内置内容。
如果某个项目需要额外的工具或环境变量,添加一个小型项目配置即可,而不必 fork 整个基础镜像:
# .yolobox.toml
env = ["CODEX_HOME=/home/yolo/.codex-account"]
[customize]
packages = ["default-jdk", "maven"]
然后正常运行:
yolobox run mvn --version
项目级自定义还可以在基础镜像之上叠加一个 Dockerfile 片段。首次运行会构建一个派生镜像;后续运行会复用它,直到基础镜像或自定义输入发生变化。
环境变量值请使用容器路径,因为它们会被直接传递给 yolobox 内部的进程。env 值会原样传递给运行时;其中的任何内容都不会被解释。
若要向沙箱传递与宿主机同名变量不同的值——例如用只读令牌代替你的真实令牌——请使用 env_from_host(或 --env-from-host KEY=HOST_VAR)为其设置别名:
# .yolobox.toml
env_from_host = ["GH_TOKEN=YOLOBOX_READONLY_GH_TOKEN"]
该别名拥有该变量:它会抑制同一键的自动透传和 --gh-token,并且如果主机变量未设置,yolobox 会拒绝启动,因此它所替换的令牌绝不会意外泄露。
有关项目环境设置,请参阅 Configuration;有关软件包安装、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 claude --claude-config --no-claude-auth # Share config, keep the box login independent
yolobox copilot --copilot-config # Share Copilot settings, login, and session history
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 and ACP adapters in the persistent box
yolobox reset --force # Remove yolobox volumes from the configured runtime
Reset 支持 Docker、Podman 和 Apple container。它只删除现有的 yolobox 卷,当没有剩余卷时也能成功执行。yolobox uninstall --force 也会在移除二进制文件和全局配置之前清理这些卷;运行时故障会中止卸载,以便之后重试。在卸载时添加 --keep-volumes 可保留运行时数据。
镜像捆绑了 OpenCode v2(@opencode/cli)。yolobox update-agents opencode 也会安装 v2,并会先从持久化 npm 前缀中移除旧的 opencode-ai 包,以避免启动器冲突。安装过程会显式允许所需的 postinstall 脚本。用户已安装的 v1 副本会保留在原处,直到你更新它们;仅拉取新镜像不会替换持久化工具。
OpenCode v2 保留 opencode 命令和现有配置位置。切换前请备份你的设置:v1 插件和服务器 API 集成需要迁移。请参阅上游迁移指南。
--claude-config 会增量同步持久化的 Claude 设置,并以读写方式实时挂载宿主机的 ~/.claude/projects,使会话恢复历史保持最新。--no-claude-auth 保持容器内登录独立,但不会使该项目历史挂载变为只读。--copilot-config 对 GitHub Copilot CLI 执行相同操作:它同步持久化的 ~/.copilot 设置、agents、skills 和 MCP 配置,将宿主机的 Copilot 登录转发为 COPILOT_GITHUB_TOKEN,并以读写方式实时挂载 ~/.copilot/session-state;添加 --no-copilot-auth 可保持容器内的 Copilot 登录独立。
自动 RTK 设置会在不提示的情况下应用受支持的 CLI 集成,包括在 OpenCode 首次启动时,并且除非你在容器内通过 rtk telemetry enable 交互式选择启用,否则遥测保持禁用。
详细参考资料有意放在文档站点中:
fork 和示例yolobox 是为 AI agents 设计的,不是为人类设计的。你启动 AI,然后让它工作。
agent 在容器内拥有 sudo 权限。如果它需要编译器、数据库、包或框架,它可以自行安装。命名卷会在会话之间保留这些设置,因此你不必把 README 变成上百行的包矩阵。把它指向你的项目,让它自由发挥。
使用相同运行时和架构的盒子会共享其持久化 home、cache 和 output 卷,包括 SELinux 主机上并发的 rootless Podman 盒子。使用 --scratch 可在不共享这些卷的情况下运行。
yolobox 用于防止意外,而不是一个神奇的防容器逃逸定理。
它有助于保护你的 home 目录、SSH 密钥、dotfiles、无关项目以及大多数宿主机文件系统状态,免受粗心破坏性命令的影响。它不保护你挂载的项目目录、你显式转发的机密、你显式桥接的宿主机操作,也不保护宿主机内核免受运行时逃逸漏洞的影响。
如需更严格的盒子,可组合使用如下标志:
yolobox claude --no-network --no-env-passthrough --readonly-project --exclude ".env*" --exclude "secrets/**"
如果你担心的是恶意代码而非疏忽大意的代码,请使用更强的隔离方式,例如无根 Podman 或虚拟机。完整的威胁模型和加固选项见 Security Model。
make build
make test
make lint
make image
贡献者工作流程、文档站点命令、版本管理和发布规则见 Contributing。
MIT