kunalkushwaha/Kagebox

# Kagebox [](https://github.com/kunalkushwaha/Kagebox/actions/workflows/ci.yml)  [](LICENSE) [Hermes Agent](https://github.com/NousResearch/hermes-agent) 可以执行任意 shell， 编辑文件，并驱动浏览器 —— 因此 **Kagebox** 将其运行在 **KVM microVM** 中 （拥有独立的内核），它无法触及你的宿主机；同时通过一个**保持 API 密钥留在宿主机上的 bridge** 来访问 LLM。本地模型（Ollama）或云端大脑（Gemini, Claude, ……） 只需一条命令即可切换，并且即使 VM 崩溃，agent 的记忆也能得以保存。 ## 架构

**bridge** 是从沙箱到宿主机的唯一通道。密钥存放在 `bridge/secrets.env`（宿主机端，已被 git-ignore）中，并被注入到请求里 —— 它们永远不会 进入 VM。Provider 是一个运行时注册表（`bridge/providers.json`）。 ## 环境要求 - Linux 宿主机，需要 **KVM**（`/dev/kvm`）、**[multipass](https://multipass.run)** 和 **[Ollama](https://ollama.com)**（用于本地模型）。 - 运行 `./kagebox doctor` 一次性检查所有配置。 ## 快速开始 ``` git clone https://github.com/kunalkushwaha/Kagebox.git && cd Kagebox ./kagebox doctor # verify host prerequisites ./kagebox setup # build the VM, bridge, and install Hermes (~10 min) ./kagebox shell # enter the sandbox, then run: hermes ``` 使用云端大脑进行繁重的研究（密钥保留在宿主机端）： ``` cp bridge/secrets.env.example bridge/secrets.env echo 'GEMINI_API_KEY=...' >> bridge/secrets.env # free key: aistudio.google.com ./kagebox bridge start ./kagebox backend gemini ``` ## 命令 | 命令 | 功能描述 | |---|---| | `./kagebox doctor` | 对宿主机进行飞行前检查 | | `./kagebox setup` / `destroy` | 构建 / 销毁沙箱 | | `./kagebox up` / `down` / `status` | 启动 / 停止 / 查看状态 | | `./kagebox shell` | 通过 shell 进入 VM（然后运行 `hermes`） | | `./kagebox backend ` | 切换模型：`ollama` · `claude` · `gemini` · … | | `./kagebox providers` | 列出后端及云服务提供商 | | `./kagebox telegram` | 设置 Telegram 机器人以与 Hermes 聊天 | | `./kagebox egress on` / `off` | 网络出口白名单（用于隔离控制） | | `./kagebox audit` | 审查 agent 的 API 调用日志 | | `./kagebox backup` / `restore` | 将 Hermes 记忆快照备份 / 恢复到宿主机 | | `./kagebox usage` | 每个提供商的 token 使用量及粗略成本 | | `./kagebox snapshot` / `snapshots` / `rollback` | VM 时间点快照 | | `./kagebox task ""` | 在一个一次性的、限制出口的 VM 克隆中运行单独的任务 | ## 后端 - **`ollama`** —— 在你的 GPU/CPU 上运行本地模型。免费、私密、离线可用。最适合快速的 工具驱动任务。（小型模型作为*工具驱动*即可胜任；参见 `evals/model_eval.py`。） - **`gemini` / `anthropic` / `openrouter`** —— 通过 bridge 访问云端大脑（密钥保留在宿主机端）。 最适合真正的多步骤研究。可在 `bridge/providers.json` 中添加任何兼容 OpenAI 的 API。 - **`claude`** —— 宿主机的 `claude -p`（使用你现有的 Claude 授权，无需 API 密钥）， 调用时禁用工具；同时也可作为“咨询更强模型”的技能供 agent 使用。 ## 记忆与文件 - **`workspace/`** —— 双向共享文件夹；agent 会将生成的文件保存在这里，并且它们会 出现在你的宿主机上。Agent 会被指示默认将输出存放在这里。 - **`hermes-state/`** —— agent 的记忆（SQLite + sessions）每 10 分钟以及在执行 `down` 时 都会在这里生成快照，并在重建时恢复。即使销毁 VM，你的记忆也能保留下来。 ## 安全性 这是一个用于隔离不可信 agent 行为的容器工具。**[SECURITY.md](SECURITY.md)** 记录了完整的威胁模型 —— 包括哪些内容被隔离了（宿主机文件系统、内核、凭证），以及 哪些没有（在启用白名单之前，出口网络默认是开放的）。对于不可信的任务： 请执行 `./kagebox egress on`。 ## 贡献 请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)**。无需构建步骤 —— 它完全由 shell + stdlib Python 编写。 ## 许可证 [MIT](LICENSE)

标签：AI智能体, AI风险缓解, Cutter, KVM, 开发运维, 沙箱环境, 虚拟化, 逆向工具, 隔离执行