AI代理镜像

Requirements

• Nix with flakes enabled
• Podman or Docker for loading and running images

All other dependencies (including agent packages from llm-agents.nix) are resolved automatically by the Nix flake. NixOS users should also follow the rootless Podman setup steps below.

macOS: Images are Linux-only. On macOS, specify the target system explicitly and ensure you have a Linux remote builder configured (e.g. via Docker Desktop or nix-darwin's linux-builder):

```bash nix build .#packages.x86_64-linux.<agent>

Build an image first (creates a `result` symlink, which is gitignored)

NixOS: Rootless Podman Setup

NixOS requires extra configuration for rootless Podman to work with these images. Add the following to your configuration.nix:

virtualisation = {
  containers.enable = true;
  podman = {
    enable = true;
    dockerCompat = true;
  };
};

users.users.<USERNAME> = {
  extraGroups = [ "podman" ];
  subUidRanges = [{ startUid = 100000; count = 65536; }];
  subGidRanges = [{ startGid = 100000; count = 65536; }];
};

Then rebuild: sudo nixos-rebuild switch

Note: The sudo commands and podman load/podman system reset commands below must be run from your own terminal. Sandboxed environments (such as AI coding agents running inside containers) cannot execute sudo or access /etc/subuid due to the "no new privileges" flag.

You also need a container trust policy. Create ~/.config/containers/policy.json:

{
  "default": [{ "type": "insecureAcceptAnything" }]
}

Quick Start

```bash

Standalone Usage

Pass the API key for your chosen provider:

```bash

Usage with agent-box

Global Configuration

Create ~/.agent-box.toml:

```toml workspace_dir = "~/.local/agent-box/workspaces" base_repo_dir = "~/path/to/your/projects"

[runtime] backend = "podman"

Adding direnv

direnv is not included by default but can be added via extraPackages:

mkAgentImage {
  name = "my-agent";
  agent = my-agent-package;
  entrypoint = [ "my-agent" ];
  withNix = true;
  extraPackages = [ pkgs.direnv pkgs.nix-direnv ];
};

You will also need to wire up the shell hook. Add an extraEnv entry or configure .bashrc in the container's home directory to run eval "$(direnv hook bash)".

Overriding Base Packages

By default, images include a standard set of CLI tools (bash, coreutils, git, etc.). Pass basePackages to replace them entirely:

mkAgentImage {
  name = "my-minimal-agent";
  agent = my-agent-package;
  entrypoint = [ "my-agent" ];
  basePackages = with pkgs; [ bashInteractive coreutils git cacert ];
}

Troubleshooting

Corrupted storage after failed load. If podman load fails (e.g. because /etc/subuid was missing), Podman's storage may be corrupted. Fix with:

podman system reset --force
podman load < result

newuidmap: Too many levels of symbolic links. This happens when /etc/subuid is a symlink (e.g. from environment.etc entries). NixOS setuid wrappers cannot follow symlinks. Remove any environment.etc entries for subuid/subgid and rely solely on subUidRanges/subGidRanges, which create real files. Rebuild and then reset Podman storage.