bounded-systems/claude-box

# claude-box 一个**固定的、隔离的、多账号的 Claude runtime** — Claude Code 运行于一个 内容寻址的 OCI container 中，每个账号对应一个 volume，由 nix 可复现地构建。每个账号的认证/历史记录/项目都存放在各自的 podman volume 中； container 本身不带任何凭证（参见 [CAPABILITIES.md](./CAPABILITIES.md)）。 ## 快速开始 **前置条件：**[nix](https://nixos.org/download)（包含 flakes），[podman](https://podman.io/docs/installation) + `podman machine` (macOS) **macOS — 一条命令：** `nix run .#setup` 会完成整个启动流程（前置检查 → `podman machine` → 构建+加载镜像 → 在 TCP 上启动 doors）。然后，在 另一个终端中： ``` nix run .#setup # one-time bringup, leaves doors running DOORS_TCP=1 claude-box --room dev --repo . # launch a box (TCP mode — see note below) ``` 在 macOS 上，doors 运行在 **TCP 模式** (`DOORS_TCP=1`)：virtiofs 无法 跨 macOS ↔ podman-machine 边界共享 Unix sockets，因此 daemons 监听在 TCP 端口上，容器通过 `host.containers.internal` 访问它们。 **手动 / Linux：** ``` # 1. 构建并加载 Claude 镜像 nix build .#claude-image && podman load -i result # 2. 初始化 door 服务（一次性设置；Linux/quadlet） claude-box doors init # 3. 以完整权限启动 claude-box --room dev --repo . # 或者快速启动而不使用 door（不安全，但可立即运行）： claude-box --net-open --repo . ``` **在家里自托管？** 原生 Linux 主机是最简单的方式（无需 podman-machine 虚拟机，没有 door 墙）。请参阅 **[HOSTING.md](./HOSTING.md)** 获取硬件 建议（ARM64 *和* x86_64 都是首选支持架构）以及无头启动指南。 ## 使用 ``` claude-box # 'personal' account (no network — see --net) claude-box work # 'work' account — separate auth/history claude-box work --resume # flags pass through to claude claude-box work --net # policed egress via the netd door (allowlist) claude-box ls # list accounts (+ descriptions) claude-box name work "Acme, Inc. — billing@acme" # friendly label ``` 账号首次运行 → 执行一次 `/login`；它会持久化保存在该账号的 volume （`claude--config`）中。名称格式不限；标签存放在 `~/.config/claude-box/accounts.json` 中。 容器限制了 box 可以*写入*的内容，而不是它可以*访问*的内容 — 因此 **出口访问是一种授权**：box 默认运行 `--network=none`，并且只能 通过 **netd** door (`--net`) 访问网络，该 door 会强制执行一个允许列表 （`--net-open` 是一个显式的、不安全的完全出口逃生通道）。请参阅 [CAPABILITIES.md](./CAPABILITIES.md) — 以及 [OCAP.md](./OCAP.md) 了解这种 应用了对象能力设计的方法在既定经典中的位置。 ## 设计 — 为任何访客准备的房间 能力引擎（door → room → rulebook）与访客无关，位于 [`guest-room/`](./guest-room/) 中 — 这是一个内部依赖项，`claude-box` 通过 提供自己的 door 目录和 room 包来使用它。该模型是一个**酒店**： 由相邻的门连接起来的独立房间，每扇门通向一个代理服务， 绝不触及钥匙或整栋建筑。文章 [*The Guest Room*](./drafts/the-guest-room.md) 完整讲述了这个故事； 拓扑结构（host / VM / room）详见 [ROOM.md](./ROOM.md)。 ## 安装 (home-manager) ``` inputs.claude-box.url = "github:bounded-systems/claude-box"; # … home.packages = [ inputs.claude-box.packages.${system}.claude-box ]; ``` `claude-box` 是一个使用 TypeScript 类型标明的 Bun CLI，由 nix 构建（一个固定版本的 bun 启动器 — `bun --compile` 无法在 nix 沙盒中运行）。它需要 **podman** + 正在运行的 `podman machine`，并且需要加载镜像（见下文）。 ## 镜像 `packages.{aarch64,x86_64}-linux.claude-image` — 基于固定版本 nixpkgs 构建的 `dockerTools.buildLayeredImage` （包含 `claude-code` + git, gh, ripgrep, fd, bun, openssh…）， 使用非 root 用户 `claude`，以及一个 config-volume 挂载点。生成的 OCI 镜像 通过其自身的 **sha256 digest**（即固定标签）进行寻址。两种 Linux 架构 均可开箱即用地构建（每种架构都固定了其自己的 `prx` 发行版 + glibc loader）；请参阅 [HOSTING.md](./HOSTING.md)。 构建需要一个 `aarch64-linux` 构建器。在 Apple Silicon 上，请使用 **vz** （Apple Virtualization.framework）构建器 — QEMU `nix run .#linux-builder` 在 M3/M4 上会崩溃（`HV_SYS_REG_SMCR_EL1`）；请参阅 **[BUILD.md](./BUILD.md)** 了解 完整设置： ``` nix build .#claude-image # offloads to the Linux builder podman load -i result # → localhost/claude-personal:dev ``` 特意使用 `buildLayeredImage`（而不是 `streamLayeredImage`）：流式处理脚本是一个 无法在 darwin 宿主机上运行的目标架构可执行文件；而 tarball 可以在 任何地方加载。 ## 开发 ``` # 运行测试（单元测试不需要 podman） bun test # 类型检查 bun x tsc --noEmit # `bunx` is a separate binary not all bun installs ship; `bun x` always works ``` 提交/PR 标题遵循 [Conventional Commits](https://www.conventionalcommits.org/) （发行版即从中切割而来）— 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 和 [RELEASING.md](./RELEASING.md)。 ### 启动 doors (daemons) `--room dev` 预设需要三个 daemons：keeperd（git 签名）、scoutd （外部读取）和 netd（出口访问允许列表）。 **一次性设置**（构建镜像，安装 systemd 单元，启动服务）： ``` claude-box doors init ``` 这在 podman-machine (macOS) 或原生 systemd (Linux) 上运行。初始化之后： ``` claude-box doors status # check service status claude-box --room dev --repo . # launch with all doors ``` **手动启动 daemon**（替代 quadlet 的方案）： ``` nix run .#keeperd -- serve # → ~/.claude-box/run/keeperd.sock nix run .#scoutd -- serve # → ~/.claude-box/run/scoutd.sock nix run .#netd -- serve # → ~/.claude-box/run/netd.sock ``` 每个 daemon 都会以安全的权限 (0700) 自动创建 `~/.claude-box/run/`。 使用 `--socket PATH` 或环境变量（`KEEPERD_SOCK` 等）覆盖 socket 路径。 ### 快速开始（无 daemons） 要在没有完整 door 设置的情况下进行开发，请使用不安全的逃生通道： ``` claude-box --net-open --repo . # unrestricted egress, no daemon needed ``` ## 状态 从 prx `claude-runtime` 工作中提取（ADR：[ADR.md](./ADR.md)）。prx 的 **builder actor** 是镜像的预期生产者/签名者；此仓库是 独立的源码。

标签：AI代理, NIDS, Nix, Podman, 容器化, 开发环境, 沙箱, 自动化攻击, 隔离运行时