yolobox

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

让你的 AI 全力输出。你的主目录依然安全。

文档：yolobox.dev

更新日志：CHANGELOG.md

在“yolo 模式”下运行 Claude Code、Codex、Kimi Code、Gemini、Antigravity、OpenCode、Copilot、Pi 或任何 AI 编码代理，而不会搞砸你的主目录。

问题所在

当你允许 AI 编码代理无需询问即可运行命令时，它们会变得异常强大。但一次误解的提示词加上 rm -rf ~，你就得从备份中恢复了（好吧，说得好像你有备份似的，哈哈）。

解决方案

yolobox 将你的 AI 代理运行在容器内，其中：

• 你的项目目录挂载在其真实路径下，例如 /Users/you/project
• 代理在容器内拥有完整权限和 sudo
• 除非你明确选择加入，否则不会挂载你的主目录
• 持久化卷可在多次运行之间保留工具、配置和会话
• Claude、Codex 和 Kimi Code 内置了 yolobox 指南，以便它们理解自己所处的沙箱环境

AI 可以在沙箱内完全放飞自我。而你真正的主目录？不可触碰。

快速开始

# 通过 Homebrew 安装
brew install finbarr/tap/yolobox

# 或通过脚本安装
curl -fsSL https://raw.githubusercontent.com/finbarr/yolobox/master/install.sh | bash

然后在任意项目中：

cd /path/to/your/project
yolobox claude    # 放手一搏

其他 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、Node.js、Python、Go、Bun、构建工具、Git、GitHub CLI、ripgrep、fd、fzf、jq、vim、RTK 以及常用的实用工具。

还需要别的？代理有 sudo。

在 yolobox 内部，受支持的 AI CLI 会被包装以跳过权限提示。没有确认，没有护栏。只有纯粹、无过滤的 AI，正如大自然所愿。

完整的工具列表、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 会拒绝启动，因此它所替换的令牌绝不会意外泄漏进来。

项目环境设置请参阅 配置，软件包安装、Dockerfile 片段、重建行为、升级行为以及完全自定义镜像请参阅 项目级自定义。

常见工作流

yolobox setup                         # 配置全局默认值
yolobox config                        # 显示此项目的已解析配置
yolobox claude --docker --gh-token    # 授予代理 Docker 和 GitHub 访问权限
yolobox claude --claude-config --no-claude-auth # 共享配置，保持盒子登录独立
yolobox codex --rtk                   # 启用 RTK 命令输出压缩
yolobox run --no-network make test    # 在无网络环境下运行单条命令
yolobox fork --name bruno codex       # 为代理提供其自己的项目副本
yolobox upgrade                       # 更新二进制文件并拉取最新镜像
yolobox update-agents                 # 更新持久化盒子中的 AI CLI

--claude-config 会增量同步持久的 Claude 设置，并实时挂载宿主机 ~/.claude/projects（读写），使会话恢复历史保持最新。--no-claude-auth 保持盒子登录独立，但不会将该项目历史挂载设为只读。

自动 RTK 设置默认保持遥测禁用，除非你在盒子内通过 rtk telemetry enable 交互式选择启用。

详细参考文档有意放在文档站点中：

• 命令：快捷方式、维护命令、fork 和示例
• 配置：全局配置、项目配置、复制的指令、环境变量透传和上下文清单
• 标志：每个标志、兼容性说明和运行时透传细节
• 配方：并行代理和 Web 应用路由

理念：这是 AI 的盒子，不是你的

yolobox 是为 AI 代理设计的，而不是为人类。你启动 AI，然后让它去工作。

代理在容器内拥有 sudo。如果它需要编译器、数据库、软件包或框架，它可以自行安装。命名卷会在多次会话之间保留这些设置，因此你无需将 README 变成一份上百行的软件包矩阵。把它指向你的项目，然后让它尽情发挥。

安全模型

yolobox 是防止意外事故的保护措施，而不是神奇的防容器逃逸定理。

它有助于保护你的主目录、SSH 密钥、点文件、无关项目以及大多数宿主机文件系统状态免受粗心大意的破坏性命令影响。它不保护你挂载的项目目录、你明确转发的机密信息、你明确桥接的宿主机操作，也不保护宿主机内核免受运行时逃逸漏洞的影响。

如需更严密的盒子，可组合使用以下标志：

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

如果你担心的是恶意代码而非粗心代码，请使用更强的隔离措施，例如 rootless Podman 或虚拟机。完整的威胁模型和加固选项见 安全模型。

开发

make build
make test
make lint
make image

贡献者工作流、文档站点命令、版本管理和发布规则见 贡献指南。

许可证

MIT