yolobox

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

让你的 AI 火力全开。你的主目录依旧安全无虞。

文档：yolobox.dev

更新日志：CHANGELOG.md

运行 Claude Code、Codex、Kimi Code、Gemini、Antigravity、OpenCode、Copilot、Pi 或任何 AI 编码代理，启用 "YOLO 模式" 而不会炸掉你的主目录。

问题

当你让 AI 编码代理无需询问权限即可运行命令时，它们会变得异常强大。但一旦误解提示词，接着一条 rm -rf ~，你就只能从备份中恢复（对，说得好像你有备份似的，哈哈）。

解决方案

yolobox 在你的 AI 代理运行于容器内时：

• 你的项目目录会挂载在其真实路径，例如 /Users/you/project
• 代理在容器内拥有完整权限和 sudo
• 除非你显式选择加入，否则不会挂载你的主目录
• 持久化卷跨运行保留工具、配置和会话
• Claude、Codex 和 Kimi Code 内置 yolobox 引导，使它们能够理解自己运行所在的沙箱

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

快速开始

# 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，希望在沙箱中执行单条命令时使用 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 片段。首次运行会构建一个派生镜像；后续运行会复用该镜像，直到基础镜像或自定义输入发生变化。

env 值应使用容器路径，因为它们会直接传给 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                         # 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 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

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

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

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

yolobox 是为 AI 代理设计的，而不是为人设计的。你启动 AI，然后让它干活。

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

安全模型

yolobox 提供的是针对意外事故的保护，而不是什么神奇的防容器逃逸定理。

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

要获得更严密的沙箱，可以组合使用以下标志：

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

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

开发

make build
make test
make lint
make image

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

许可证

MIT