nothingnesses/agent-images
GitHub: nothingnesses/agent-images
基于 Nix 可复现构建的沙箱化 OCI 容器镜像集合，用于安全隔离各类 AI 编程 agent，防止其越权访问宿主机敏感文件。
Stars: 11 | Forks: 2
# agent-images
使用 Nix 可复现构建的，专为 AI 编程 agent 设计的沙箱化 OCI 容器镜像。
消费来自 [llm-agents.nix](https://github.com/numtide/llm-agents.nix) 的 agent 包，并生成可通过 [agent-box](https://github.com/0xferrous/agent-box) 或独立 Podman/Docker 使用的镜像。
```
llm-agents.nix (packages) -> agent-images (images) -> agent-box (orchestration)
```
## 为什么
AI 编程 agent 需要访问你的文件系统才能发挥作用，但这意味它们也可以读取诸如 SSH 密钥、云凭证和 API token 之类的秘密信息。
在容器中运行 agent 可以限制它们的可见范围。Nix 使镜像具备可复现性且易于定制。
## 可用镜像
#### AI 编程 Agent
| 镜像 | Agent | 构建 |
| ---------------- | ----------------------------------------------------------------- | ---------------------------- |
| `amp` | [Amp](https://ampcode.com/) | `nix build .#amp` |
| `claude-code` | [Claude Code](https://claude.ai/code) | `nix build .#claude-code` |
| `cli-proxy-api` | [CLI Proxy API](https://github.com/router-for-me/CLIProxyAPI) | `nix build .#cli-proxy-api` |
| `code` | [Code](https://github.com/just-every/code/) | `nix build .#code` |
| `codex` | [Codex CLI](https://github.com/openai/codex) | `nix build .#codex` |
| `copilot-cli` | [Copilot CLI](https://github.com/github/copilot-cli) | `nix build .#copilot-cli` |
| `crush` | [Crush](https://github.com/charmbracelet/crush) | `nix build .#crush` |
| `cursor-agent` | [Cursor Agent](https://cursor.com/) | `nix build .#cursor-agent` |
| `droid` | [Droid](https://factory.ai) | `nix build .#droid` |
| `eca` | [ECA](https://github.com/editor-code-assistant/eca) | `nix build .#eca` |
| `forge` | [Forge](https://github.com/antinomyhq/forge) | `nix build .#forge` |
| `gemini-cli` | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `nix build .#gemini-cli` |
| `goose-cli` | [Goose](https://github.com/block/goose) | `nix build .#goose-cli` |
| `iflow-cli` | [iFlow CLI](https://github.com/iflow-ai/iflow-cli) | `nix build .#iflow-cli` |
| `jules` | [Jules](https://jules.google) | `nix build .#jules` |
| `kilocode-cli` | [Kilocode CLI](https://kilocode.ai/cli) | `nix build .#kilocode-cli` |
| `letta-code` | [Letta Code](https://github.com/letta-ai/letta-code) | `nix build .#letta-code` |
| `mistral-vibe` | [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | `nix build .#mistral-vibe` |
| `nanocoder` | [Nanocoder](https://github.com/Mote-Software/nanocoder) | `nix build .#nanocoder` |
| `oh-my-opencode` | [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-openagent) | `nix build .#oh-my-opencode` |
| `omp` | [OMP](https://github.com/can1357/oh-my-pi) | `nix build .#omp` |
| `opencode` | [OpenCode](https://github.com/anomalyco/opencode) | `nix build .#opencode` |
| `pi` | [Pi](https://github.com/badlogic/pi-mono) | `nix build .#pi` |
| `qoder-cli` | [Qoder CLI](https://qoder.com) | `nix build .#qoder-cli` |
| `qwen-code` | [Qwen Code](https://github.com/QwenLM/qwen-code) | `nix build .#qwen-code` |
#### AI 助手
| 镜像 | Agent | 构建 |
| -------------- | ------------------------------------------------------ | -------------------------- |
| `hermes-agent` | [Hermes Agent](https://hermes-agent.nousresearch.com/) | `nix build .#hermes-agent` |
| `localgpt` | [LocalGPT](https://github.com/localgpt-app/localgpt) | `nix build .#localgpt` |
| `openclaw` | [OpenClaw](https://openclaw.ai) | `nix build .#openclaw` |
| `picoclaw` | [PicoClaw](https://picoclaw.io) | `nix build .#picoclaw` |
| `zeroclaw` | [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw) | `nix build .#zeroclaw` |
每个镜像都包含一组默认的基础包：git, coreutils, bash, ripgrep, findutils, grep, sed, gawk, diff, jq, tar, gzip, less, curl, which 和 CA 证书。可以通过 `basePackages` 参数覆盖它们（参见[自定义镜像](#custom-images))。默认情况下，容器以非 root 的 `agent` 用户 (uid 1000) 运行，并将 `/workspace` 作为工作目录。镜像还会在 `$HOME` 下预先创建标准的 XDG 基础目录 (`.config`, `.cache`, `.local/share`, `.local/state`)，这样将子路径挂载到这些目录时就不会留下属于 root 用户的父目录。用户和工作目录都可以自定义（参见[自定义镜像](#custom-images))。
## 系统要求
- 启用了 [flakes 支持](https://wiki.nixos.org/wiki/Flakes) 的 [Nix](https://nixos.org/)
- 用于加载和运行镜像的 [Podman](https://podman.io/) 或 [Docker](https://www.docker.com/)
所有其他依赖项（包括来自 [llm-agents.nix](https://github.com/numtide/llm-agents.nix) 的 agent 包）都将由 Nix flake 自动解析。NixOS 用户还应遵循下面的 [rootless Podman 设置](#nixos-rootless-podman-setup) 步骤。
**macOS：** 镜像仅支持 Linux。在 macOS 上，需要明确指定目标系统，并确保你配置了 [Linux 远程构建器](https://nix.dev/manual/nix/latest/advanced-topics/distributed-builds)（例如通过 Docker Desktop 或 nix-darwin 的 `linux-builder`）：
```
nix build .#packages.x86_64-linux.
# 或对于 ARM：
nix build .#packages.aarch64-linux.
```
开发工具（`nix fmt`, `nix develop`, `nix flake check`）可以在 macOS 上原生运行。
## 快速入门
```
# 列出所有可用镜像及其描述
nix search . ^
# 将 替换为上表中的任意镜像名称
nix build .#
podman load < result # or: docker load < result
podman run --rm localhost/agent-images/:latest --version
```
### 独立使用
为你选择的提供商传入 API key：
```
# Claude Code (Anthropic)
podman run --rm -it \
-v ./my-project:/workspace \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
localhost/agent-images/claude-code:latest
# OpenCode (OpenRouter)
podman run --rm -it \
-v ./my-project:/workspace \
-e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
localhost/agent-images/opencode:latest
```
### 验证容器内部结构
```
# 将 替换为上面使用的镜像名称
podman run --rm --entrypoint sh localhost/agent-images/:latest \
-c 'whoami && echo $HOME && pwd && command -v git && command -v rg'
```
预期输出：
```
agent
/home/agent
/workspace
/nix/store/.../bin/git
/nix/store/.../bin/rg
```
## 配合 agent-box 使用
### 全局配置
创建 `~/.agent-box.toml`：
```
workspace_dir = "~/.local/agent-box/workspaces"
base_repo_dir = "~/path/to/your/projects"
[runtime]
backend = "podman"
# 将 替换为上表中的任意镜像名称
image = "localhost/agent-images/:latest"
env_passthrough = ["ANTHROPIC_API_KEY", "OPENROUTER_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY"]
```
`base_repo_dir` 必须是包含你 git 仓库的实际（非符号链接的）父目录。Agent-box 会解析符号链接，因此将仓库符号链接到单独的目录将不起作用。将你的 agent 需要的任何其他 API key 添加到 `env_passthrough` 中。
### 本地模式
将当前目录原样挂载到容器中。agent 可以看到所有文件，包括未跟踪和被 gitignore 的文件。
```
cd ~/projects/my-repo
ab spawn --local
```
### Worktree 模式（沙箱化）
创建一个 git worktree，使 agent 只能看到已提交/跟踪的文件。被 gitignore 的文件（如 `result`）将不可见。
```
# 创建一个工作区（在 repo 目录内）
ab new my-repo -s my-session --git
# 启动容器
ab spawn -s my-session --git
```
### 运行一次性命令
使用 `--entrypoint` 覆盖默认的 entrypoint，并使用 `-c` 传递参数：
```
# 检查 agent 版本
ab spawn --local --entrypoint -c="--version"
# 读取文件
ab spawn --local --entrypoint cat -c="README.md"
# 运行 shell 命令（注意：将每个参数作为单独的 -c 传递）
ab spawn --local --entrypoint sh -c="-c" -c="whoami && pwd"
```
### 沙箱验证
要验证 worktree 模式是否会隐藏被 gitignore 的文件：
```
# 首先构建一个镜像（创建一个 `result` 软链接，该链接已被 gitignore）
# 将 替换为上表中的任意镜像名称
nix build .#
# 本地模式 - agent 可以看到 result
ab spawn --local --entrypoint ls -c="-la" -c="result"
# 输出：result -> /nix/store/...
# Worktree 模式 - agent 无法看到 result
ab new my-repo -s sandbox-test --git
ab spawn -s sandbox-test --git --entrypoint ls -c="result"
# 输出：ls: cannot access 'result': No such file or directory
```
## NixOS：Rootless Podman 设置
NixOS 需要额外的配置才能在这些镜像上使用 rootless Podman。请将以下内容添加到你的 `configuration.nix` 中：
```
virtualisation = {
containers.enable = true;
podman = {
enable = true;
dockerCompat = true;
};
};
users.users. = {
extraGroups = [ "podman" ];
subUidRanges = [{ startUid = 100000; count = 65536; }];
subGidRanges = [{ startGid = 100000; count = 65536; }];
};
```
然后重新构建：`sudo nixos-rebuild switch`
**注意：** 下面的 `sudo` 命令以及 `podman load`/`podman system reset` 命令必须在你自己的终端中运行。沙箱化环境（例如在容器内运行的 AI 编程 agent）由于启用了 "no new privileges" 标志，无法执行 `sudo` 或访问 `/etc/subuid`。
你还需要一个容器信任策略。创建 `~/.config/containers/policy.json`：
```
{
"default": [{ "type": "insecureAcceptAnything" }]
}
```
### 故障排除
**加载失败后存储损坏。** 如果 `podman load` 失败（例如因为缺少 `/etc/subuid`），Podman 的存储可能会损坏。修复方法如下：
```
podman system reset --force
podman load < result
```
**`newuidmap: Too many levels of symbolic links`。** 当 `/etc/subuid` 是一个符号链接（例如来自 `environment.etc` 条目）时，就会发生这种情况。NixOS 的 setuid 包装器无法跟随符号链接。请移除 `subuid`/`subgid` 的所有 `environment.etc` 条目，仅依赖 `subUidRanges`/`subGidRanges`，它们会创建真实文件。重新构建并重置 Podman 存储。
## 自定义镜像
使用 `mkAgentImage` 构建你自己的 agent 镜像：
```
{
inputs.agent-images.url = "github:nothingnesses/agent-images";
outputs = { agent-images, nixpkgs, ... }:
let
pkgs = nixpkgs.legacyPackages.x86_64-linux;
mkAgentImage = agent-images.lib.mkAgentImage { inherit pkgs; };
in {
packages.x86_64-linux.my-agent = mkAgentImage {
name = "my-agent";
agent = my-agent-package;
entrypoint = [ "my-agent" ];
extraPackages = [ pkgs.nodejs ];
extraEnv = { MY_VAR = "value"; };
extraDirectories = [ "~/.my-agent-cache" "/opt/my-agent-cache" ];
};
};
}
```
### 覆盖基础包
默认情况下，镜像包含一组标准的 CLI 工具（bash, coreutils, git 等）。传入 `basePackages` 可以完全替换它们：
```
mkAgentImage {
name = "my-minimal-agent";
agent = my-agent-package;
entrypoint = [ "my-agent" ];
basePackages = with pkgs; [ bashInteractive coreutils git cacert ];
}
```
### 自定义用户和工作目录
默认情况下，容器以 `agent` 用户 (uid/gid 1000) 运行，并将 `/workspace` 作为工作目录。使用 `user`, `uid`, `gid` 和 `workingDir` 可以覆盖这些设置：
```
mkAgentImage {
name = "my-agent";
agent = my-agent-package;
entrypoint = [ "my-agent" ];
user = "dev";
uid = 1001;
gid = 100; # defaults to uid if omitted
workingDir = "/project";
}
```
独立于 `uid` 设置 `gid` 对于 host 组（例如 `users`, gid 100）与其 uid 不同的 rootless Podman 用户非常有用。如果不这样做，在容器内创建的文件的 gid 可能会映射到 host 上的意外值。
### XDG 基础目录和额外可写路径
`mkAgentImage` 始终会创建由运行时用户拥有的 `$HOME`、工作目录以及以下 XDG 基础目录：
- `$HOME/.config`
- `$HOME/.cache`
- `$HOME/.local/share`
- `$HOME/.local/state`
相应的环境变量（`XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`）也会被设置为这些默认值。如果你通过 `extraEnv` 覆盖了其中任何一个，该变量的默认设置将被抑制以避免重复。
这可以避免一个常见的容器运行时陷阱，即挂载 `/home/agent/.config/git` 等子目录会导致缺失的父目录被自动创建为 `root:root`。
如果你需要更多由运行时用户拥有的可写目录，请将 `extraDirectories` 作为绝对容器路径或相对于容器用户主目录的 `~/...` 路径传入：
```
mkAgentImage {
name = "my-agent";
agent = my-agent-package;
entrypoint = [ "my-agent" ];
extraDirectories = [
"~/.my-agent-cache"
"/opt/my-agent/state"
];
}
```
只有列出的路径会被 chown 给运行时用户。由 `mkdir -p` 为 `$HOME` 外部的路径创建的中间父目录仍归 root 所有。如果你需要可写的中间目录，请在 `extraDirectories` 中明确列出它们。
要使用非标准的 XDG 路径，请结合使用 `extraDirectories`（用于创建目录）和 `extraEnv`（用于设置环境变量）：
```
mkAgentImage {
name = "my-agent";
agent = my-agent-package;
entrypoint = [ "my-agent" ];
extraDirectories = [ "~/.custom-config" ];
extraEnv = { XDG_CONFIG_HOME = "/home/agent/.custom-config"; };
}
```
`XDG_RUNTIME_DIR` 被有意排除在外。它由 `pam_systemd` 管理，需要具有严格生命周期语义的 tmpfs，并且无法在容器镜像中有意义地预先创建。
`extraDirectories` 条目会在构建时进行验证。路径必须是绝对路径（或使用 `~/`），只能包含字母数字字符、`/`、`_`、`.`、`+`、`@` 和 `-`，并且不得包含 `..` 组件。系统路径（`/etc`, `/bin`, `/usr`, `/lib`, `/sbin`, `/dev`, `/proc`, `/sys`, `/run`, `/tmp`, `/nix`, `/var`, `/root`）将被拒绝，以防止意外更改关键目录的所有权。
## 在容器内使用 Nix
默认情况下，镜像中不包含 Nix CLI。设置 `withNix = true` 可以在容器内启用 Nix 工作流：
```
mkAgentImage {
name = "my-agent";
agent = my-agent-package;
entrypoint = [ "my-agent" ];
withNix = true;
};
```
这会配置单用户 Nix，并启用 `nix-command` 和 `flakes` 实验性特性。在容器内部，你可以运行：
```
nix --version
nix develop
nix build
nix shell nixpkgs#hello -c hello
nix-shell -p ripgrep --command "rg --version"
```
### 覆盖 Nix 版本
Nix CLI 版本默认为该 flake 的 nixpkgs 锁定的版本。传入 `nixPackage` 可使用不同的版本：
标签：agent-box, AI安全, AI编程代理, Chat Copilot, Claude Code, Cutter, DevSecOps, DLL 劫持, Docker, GitHub Copilot, llm-agents.nix, Nix, OCI容器镜像, OpenAI Codex, Podman, SOC Prime, StruQ, Web截图, 上游代理, 代码辅助, 可复现构建, 大语言模型, 安全防御评估, 容器安全, 容器编排, 密钥保护, 开发工具, 沙箱, 端侧AI, 网络安全审计, 请求拦截, 隔离执行