# yoloAI
**面向 AI 编码代理的沙箱运行器。无需权限疲劳，凭据不进入沙箱，在你批准之前不会对你的项目做任何更改。**
[](https://github.com/kstenerud/yoloai/actions/workflows/ci.yml)
[](https://github.com/kstenerud/yoloai/actions/workflows/audit.yml)
[](https://github.com/kstenerud/yoloai/releases/latest)
[](https://pkg.go.dev/github.com/kstenerud/yoloai)
[](LICENSE)
AI 编码代理在关闭护栏时表现最佳，但在你的真实机器上这样运行是非常糟糕的。yoloAI 为代理提供一个可丢弃的沙箱，它可以在其中自由编辑和运行任何内容，无需人工值守。你的项目、你的凭据和你的网络始终由你掌控。当代理完成后，审查差异并应用你想要保留的内容。
```text
你 沙箱 你的项目
│ │ │
├─ yoloai new fix-bug . ├─ 项目的沙箱副本 │
│ │ │
├─ << 你的提示词 >> ├─ 代理自由工作 │
│ │ （无权限提示） │
│ │ │
├─ yoloai diff fix-bug ├─ 显示更改内容 │
│ │ │
├─ yoloai apply fix-bug │ ├─ 应用补丁
│ （由你选择应用哪些） │ │
│ │ │
├─ yoloai destroy fix-bug ├─ 销毁沙箱 │
```
## 为什么？
权限提示的存在是因为代理会犯错。在第一百次批准/拒绝之后，你就不再阅读它们了，而 `--dangerously-skip-permissions` 距离一个困惑的代理酿成大祸只有一步之遥。yoloAI 缩小了爆炸半径，直到权限提示变得不再必要：
- **你的文件是安全的。** 代理在你的项目的隔离副本上工作。`diff` 精确显示更改内容，`apply` 在保留单个提交的同时修补你的真实项目，在你应用之前，原始文件永远不会改变。
- **你的机密是安全的。** 沙箱从一个最小的、本地构建的环境启动；主机环境变量保留在主机上。凭据以只读文件挂载的方式进入，绝不会作为环境变量。在适用凭据代理的情况下（目前为 Claude、Gemini 和 Codex，默认开启），API 密钥完全保留在主机端：一个本地代理在请求发往提供商时注入密钥，因此即使代理被完全攻破，也没有任何东西可被窃取。
- **你的网络属于你。** `--network-isolated` 将出站流量限制为代理的 API 端点以及你允许的域名。`--network-none` 完全移除网络。
- **你的机器是隔离的。** 选择你舒适的安全级别，从 Linux 命名空间到 gVisor，再到硬件虚拟机。
有关完整模型（包括诚实的局限性说明），请参阅 [安全](https://github.com/kstenerud/yoloai/blob/main/docs/GUIDE.md#security)。
## 安装
### 预编译二进制（推荐）
从 [最新发布](https://github.com/kstenerud/yoloai/releases/latest) 下载适用于你平台的压缩包，解压出 `yoloai` 二进制文件，并将其放入你的 `PATH`：
```bash
# Linux x86-64（根据需要替换为 linux_arm64 / darwin_amd64 / darwin_arm64）。
# 将 VERSION 设置为上方链接的最新发布页面中显示的标签，不带
# 开头的 "v" —— 例如标签 v1.2.3 对应 VERSION=1.2.3。
VERSION=X.Y.Z
curl -fsSL "https://github.com/kstenerud/yoloai/releases/download/v${VERSION}/yoloai_${VERSION}_linux_amd64.tar.gz" \
| tar -xz yoloai
sudo install yoloai /usr/local/bin/
```
每个压缩包还附带 shell 补全、`LICENSE` 和变更日志。发布版本使用 cosign 签名（`checksums.txt`），并带有 GitHub 构建来源证明（`gh attestation verify yoloai_… --repo kstenerud/yoloai`）。每个发布版本也附带了 Debian/RPM 软件包。
### Homebrew（macOS / Linux）
```bash
brew install --cask kstenerud/tap/yoloai
```
### 使用 `go install`
```bash
# 最新发布版本
go install github.com/kstenerud/yoloai/cmd/yoloai@latest
# 最新开发版本（不稳定）
go install github.com/kstenerud/yoloai/cmd/yoloai@main
```
需要 Go 1.26+。二进制文件位于 `$GOPATH/bin`（通常为 `~/go/bin`）。
### 从源码构建
```bash
git clone https://github.com/kstenerud/yoloai.git
cd yoloai
git checkout "$(git describe --tags --abbrev=0)" # 最新的发布标签；或停留在 main 分支使用开发版本
make build
sudo install yoloai /usr/local/bin/
```
这是一个单一的 Go 二进制文件，除了你选择的后端之外没有运行时依赖。首次运行时，yoloAI 会构建其基础镜像并创建 `~/.yoloai/`（或你通过 `--data-dir` 指定的任何目录）。
## 快速开始
### 非交互式
```bash
# 认证（yoloAI 自动获取现有凭据）
export ANTHROPIC_API_KEY=sk-ant-... # Claude Code
export GEMINI_API_KEY=... # Gemini CLI
# 或者直接让它获取你已认证的会话
# 1. 启动一个沙箱。当你提供提示词时，代理立即开始工作
yoloai new fix-bug ./my-project --prompt "修复失败的测试"
# 2. 查看代理更改了什么
yoloai diff fix-bug
# 3. 将好的部分应用到你的真实项目
yoloai apply fix-bug
# 4. 丢弃沙箱
yoloai destroy fix-bug
```
### 交互式
```bash
yoloai new exploration ./my-project -a
# 你已进入代理，它在沙箱中的 tmux 里运行。
# 按 Ctrl-B, D 分离。
# 使用 yoloai attach exploration 重新连接。
```
### 迭代
对于较长的会话，以循环方式工作：告诉代理边工作边提交，并随时从另一个终端运行 `yoloai apply`，将完成的提交拉入你的真实项目。每次 apply 只带入自上次以来的新提交。当你对结果满意时，照常推送并销毁沙箱。完整工作流程请参阅 [使用指南](https://github.com/kstenerud/yoloai/blob/main/docs/GUIDE.md)。
## 演示
创建沙箱、向代理发出提示并应用结果：
https://github.com/user-attachments/assets/9d6740b4-a34e-4253-82ec-cb0e4c7a8bd9
## 功能特性
**沙箱化**
- 六种后端：Docker、Podman、containerd（Kata）、Apple Container、Tart 和 Seatbelt。支持 Linux、macOS 和 Windows（WSL2）。
- 每个沙箱可选择的隔离强度，从 runc 到 gVisor，再到 Kata 虚拟机（QEMU 或 Firecracker）。
- 每个沙箱的网络策略：开放、白名单或无网络。
- 沙箱内部为最小化环境。来自主机的任何内容都是显式选择加入的（`--env`、`--dir`）。
- 资源限制（`--cpus`、`--memory`）和端口转发（`--port`）。
- 廉价的工作目录副本：macOS 上为整树克隆（APFS `clonefile`），支持 reflink 的 Linux 文件系统（btrfs、XFS）上为逐文件 reflink。不支持 reflink 的文件系统（ext4）则进行常规复制。
- 遵循 `.gitignore`：任何被忽略的内容都**不会**被复制到沙箱中（针对磁盘上开发凭据的安全实践）。
**凭据**
- 自动获取你现有的代理登录信息：API 密钥、订阅凭据、macOS 钥匙串。
- 凭据代理将 API 密钥保留在主机端（目前为 Claude、Gemini 和 Codex）；Aider 和 OpenCode 的凭据以只读文件挂载的方式交付。
**工作流**
- 复制/差异/应用，git 在沙箱端运行，因此带有过滤器和钩子的仓库行为正确。
- 按你的方式应用：重放提交（默认）、压缩为单个补丁、导出 `.patch` 文件、按引用选择提交，或先使用 `--dry-run`。
- 完整生命周期：创建、附加、停止、重启、等待、克隆、重置、销毁。代理状态在停止和重启后仍然保留。
- 面向脚本和 CI 的无头一次性运行：`yoloai run --prompt ... --rm`，所有命令均支持 `--json` 输出。
- 当代理退出时，其 tmux 窗格会回落到 shell，以便你检查沙箱。
**集成**
- 内置 Claude Code、Codex、Gemini CLI、Aider 和 OpenCode，另有 `shell` 模式可用于其他任何工具。
- VS Code：附加到容器，或从沙箱内部打开远程隧道（`--vscode-tunnel`）。
- 双向 MCP：`yoloai mcp serve` 让外部代理将沙箱作为工具驱动；`yoloai mcp proxy` 在沙箱内部运行 MCP 服务器。
- 配置文件：按项目定制的镜像和默认设置（Dockerfile + 配置，支持继承）。
- 扩展：以 YAML 包装的 shell 脚本添加你自己的子命令（`yoloai x`）。
- 可嵌入：CLI 是公共 [Go API](https://pkg.go.dev/github.com/kstenerud/yoloai) 之上的薄层。
- 单一静态二进制文件。状态存储在 `~/.yoloai/` 中（可通过 `--data-dir` 重定位）。
## 支持的基础设施
### 沙箱后端
| 后端 | 支持的主机 | 依赖项 |
|------------|------------------------------|--------------------------------------------------------------------|
| docker | Linux、macOS、Windows（WSL2） | [Docker Engine](https://docs.docker.com/engine/install)、[Docker Desktop](https://docs.docker.com/get-docker) 或 [OrbStack](https://orbstack.dev) |
| podman | Linux、macOS | [Podman](https://podman.io/get-started)（macOS 上使用 `brew install podman`） |
| containerd | Linux | [Kata Containers](https://katacontainers.io) |
| apple | macOS（Apple Silicon） | [Apple Container](https://github.com/apple/container) |
| tart | macOS（Apple Silicon） | [Tart](https://github.com/cirruslabs/tart)（`brew install cirruslabs/cli/tart`） |
| seatbelt | macOS（任意） | 无（使用内置的 `sandbox-exec`） |
**注意**：Tart 提供完整的 macOS 虚拟机，使你能够在沙箱内运行模拟器。
### 隔离模式
可选地升级 OCI 运行时以获得更强的隔离。gVisor 模式可用于 docker 和 podman；虚拟机模式随 containerd 后端提供。
| 模式 | 描述 |
|------|-------------|
| `container` | 默认 `runc`：标准 Linux 命名空间和 cgroups |
| `container-enhanced` | 用户空间内核（gVisor/runsc）：系统调用拦截，无需 KVM |
| `container-privileged` | 所有能力，seccomp/AppArmor 不受限制。用于 Docker-in-Docker 和 Compose |
| `vm` | Kata Containers（QEMU）：硬件虚拟机隔离 |
| `vm-enhanced` | Kata + Firecracker 微型虚拟机：轻量级虚拟机隔离 |
```bash
# 为所有新沙箱使用 gVisor
yoloai config set isolation container-enhanced
# 或按沙箱设置
yoloai new task . --isolation container-enhanced
```
### 代理
| 模式 | 描述 |
|------------|-------------|
| `claude` | 通过 API 密钥或订阅凭据运行 [Claude Code](https://github.com/anthropics/claude-code)（默认） |
| `codex` | 通过 API 密钥或订阅凭据运行 [Codex](https://github.com/openai/codex) |
| `gemini` | 通过 API 密钥或订阅凭据运行 [Gemini CLI](https://github.com/google-gemini/gemini-cli) |
| `aider` | 运行 [Aider](https://github.com/Aider-AI/aider)（你的配置会被复制进去） |
| `opencode` | 运行 [OpenCode](https://github.com/anomalyco/opencode)（你的配置会被复制进去） |
| `shell` | 运行一个 tmux shell，并预置所有代理凭据 |
| `idle` | 运行一个空闲进程以支持 MCP 代理 |
使用 `yoloai system agents` 列出可用的代理。
## 了解更多
- **[使用指南](https://github.com/kstenerud/yoloai/blob/main/docs/GUIDE.md)**：命令、标志、工作目录模式、配置、安全
- **[路线图](https://github.com/kstenerud/yoloai/blob/main/docs/ROADMAP.md)**：即将推出的功能
- **[架构](https://github.com/kstenerud/yoloai/blob/main/docs/contributors/architecture/README.md)**：面向贡献者的代码导航
## 状态
公开测试版。核心工作流稳定且每日使用；接口在 0.x 版本之间可能仍有变化，所有破坏性变更都会记录在 [BREAKING-CHANGES](https://github.com/kstenerud/yoloai/blob/main/docs/BREAKING-CHANGES.md) 中。[欢迎反馈。](https://github.com/kstenerud/yoloai/issues)
## 许可证
[MIT](https://github.com/kstenerud/yoloai/blob/main/LICENSE)
