> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime Capsule

Runtime Capsule 是在 harness setup 之前注入的通用、不可变工具链 Closure。它提供稳定的 Node/npm、Python/pip 等运行时，但不包含也不识别具体 harness。Harness 版本仍由已有的 `install_command` 或 `openhands_version` 指定。

AgentCompass 当前注册 `node24-v1`（用于 Claude Code、Codex）、`python312-v1`（用于 OpenHands）和 `python312-node24-v1`（用于需要在单个 Capsule 中提供 Python 3.12、Node 24 和 uv 的安装流程）。

## 执行流程

```text theme={"system"}
setup_capsule_tag
        │
        ▼
先检查是否可以复用已安装的 harness
        │ 需要安装时
        ▼
探测目标 OS、架构和 libc family
        │
        ▼
解析预定义文件名、SHA-256、下载地址和目标变体
        │
        ▼
校验/下载 bundle，并安装不可变 runtime closure
        │
        ▼
使用 Capsule 包管理器执行原 install_strategy
        │
        ▼
只 seal harness 自有 setup tree，然后在原始 / 中运行 harness
```

Capsule 不替代 `preinstalled`、`install_if_missing` 或 `upload`。Codex 和 Claude Code 的 `preinstalled` 路径跳过 Capsule；`install_if_missing` 找到已有 harness 时也不下载或安装 Capsule。未设置 `setup_capsule_tag` 时，继续使用原安装方式。

## Bundle 契约

v1 bundle 是根目录包含 `agentcompass-capsule.json` 的 gzip tar；分发文件名与摘要由内置 registry 定义：

```json theme={"system"}
{
  "schema_version": "agentcompass.capsule.v1",
  "runtime": {"id": "node24", "version": "24.19.0"},
  "platform": {"os": "linux", "architecture": "x86_64", "libc": "musl"},
  "install_root": "/tmp/agentcompass-capsules/node24-24.19.0-linux-x86_64-musl",
  "launcher": "bin/capsule-exec",
  "tools": {
    "node": "bin/node",
    "npm": "bin/npm",
    "npx": "bin/npx",
    "seal-tree": "bin/seal-tree"
  }
}
```

Manifest 不含 harness id、harness version 或 harness entrypoint。新构建产物的 Node/Python ABI 与 `platform.libc` 一致。一个 bundle 可以携带 glibc 和 musl 私有库，支持独立启动不同 ABI 的 ELF；这不能让 glibc 进程加载 musl 原生扩展，或反过来。

AgentCompass 校验摘要、平台、归档路径和所需工具，然后原子安装到 `/tmp/agentcompass-capsules/`。Harness 包安装到只由 Capsule 内容决定的 `/tmp/agentcompass-capsule-setups/<bundle-sha256>/` 可写目录，Capsule 本身保持不可变。

## 激活与兼容机制

Capsule 不使用 bubblewrap、chroot、替代 rootfs、mount namespace 或命令桥接。Benchmark 镜像始终是 `/`，因此 harness 看到的文件系统、设备、网络、cwd 和进程能力与原生启动一致。

Capsule launcher 只在 setup 时把工具链加入 `PATH`。最终 harness 通过绝对路径启动，不导出 Capsule `PATH`、npm prefix 或全局 `LD_LIBRARY_PATH`，所以 shell/tool 子进程解析的是 benchmark 镜像中的命令和依赖。OpenHands 在导入 harness 模块后还会移除 setup 专用的 `PYTHONPATH` 项。

安装完成后，`seal-tree` 只检查 AgentCompass 自有的 setup root。它把 Node/Python/bash shebang 指向私有运行时。对于声明 interpreter 的 ELF 可执行文件，仅当已有 loader 无法装载时，才写入匹配的私有 loader 和 RPATH；对于共享库和原生扩展，则在 RPATH 中追加匹配的私有库路径。当前每个 bundle 同时携带私有 glibc 与 musl ABI 支撑，因为同一个 npm 包也可能混用两类 ELF。该过程不修改目标系统库或全局 linker 配置。

Python 的公共入口使用 wrapper 执行实际解释器，让 uv/venv 正确记录解释器所在目录和标准库位置。安装阶段仍可能执行刚下载的原生程序，运行期也可能懒安装新依赖；这些文件不会被之后或之前的一次 `seal-tree` 自动覆盖，必须在对应安装流程中验证。

此机制解决运行时缺失或用户态依赖过旧，不能模拟 CPU 指令、内核 syscall、seccomp 权限、可执行挂载或其他架构；这些情况会直接失败，不回退到 `repair_glibc`。

Node 24 自带的 npm 会限制未批准依赖的生命周期脚本。Claude Code 和 Codex setup 会为用户明确配置的 harness 安装启用传统脚本行为，因此 `install_command` 应只指向可信包。

## 构建 Capsule

构建器支持 Docker 和 Podman，通过 `--container-cli docker` 或 `--container-cli podman` 选择，默认使用 Docker；原有 `--docker` 参数保留为兼容别名。为每种目标 libc profile 构建一个不可变产物：

```bash theme={"system"}
python tools/build_runtime_capsule.py node24 \
  dist/node24-v1-linux-x86_64-glibc.tar.gz --libc glibc
python tools/build_runtime_capsule.py node24 \
  dist/node24-v1-linux-x86_64-musl.tar.gz --libc musl

python tools/build_runtime_capsule.py python3.12 \
  dist/python312-v1-linux-x86_64-glibc.tar.gz --libc glibc
python tools/build_runtime_capsule.py python3.12 \
  dist/python312-v1-linux-x86_64-musl.tar.gz --libc musl

python tools/build_runtime_capsule.py python3.12-node24 \
  dist/python312-node24-v1-linux-x86_64-glibc.tar.gz --libc glibc
```

默认固定 Node.js 24.19.0（npm 11.17.0）和 Python 3.12.10（含 pip）。可用 `--node-version 24.x.y` 或 `--python-version 3.12.x` 选择其他精确版本。当前构建器产出 Linux x86\_64 bundle。

复合 Capsule 还提供固定版本的 uv/uvx，默认 uv 0.12.10，可通过 `--uv-version` 调整。它把 Python、Node 和安装工具放在同一个 bundle 中，适合需要两套工具链的安装流程。它不包含 Chromium 或任意工具插件的全部依赖。

本功能尚处未合入的开发阶段，迭代产物沿用现有 v1 标签和分发文件名，覆盖旧产物时同步更新 registry 的 SHA-256。控制端若缓存了旧产物，也须替换对应缓存文件；摘要校验仍保持严格。

## 在 harness 中使用

Codex：

```json theme={"system"}
{
  "install_strategy": "install_if_missing",
  "install_command": "npm install -g @openai/codex",
  "setup_capsule_tag": "node24-v1"
}
```

Claude Code 使用相同的 `setup_capsule_tag`。切换 harness 版本只修改 `install_command`，不修改 Capsule tag。

OpenHands 使用 Python Capsule：

```json theme={"system"}
{
  "openhands_version": "1.23.0",
  "setup_capsule_tag": "python312-v1"
}
```

此时 OpenHands 使用 Capsule pip 安装 SDK/tools，不再下载 micromamba。

Capsule 提供工具链而非 harness 包，`install_if_missing` 仍需要 Environment 能访问 package registry。离线环境应提供 registry cache、可离线的 `install_command`、`preinstalled` 或 `upload`。

Hermes 的裸 `AIAgent` 与完整 CLI 的配置、工具初始化和会话行为不等价。评估其安装覆盖时，应安装官方 CLI 依赖并使用官方执行入口；即使省去 TUI，本地浏览器工具仍可能需要 Node/npx、Chromium 和系统库。Python loop 可以启动，不代表完整工具集可用。

## 分发与缓存

AgentCompass 为每个逻辑 tag 及其所有目标变体内置分发文件名、SHA-256 和下载地址。用户只选择逻辑 tag，不接受任意本地路径、URL 或 OCI reference。

Bundle 保存在控制端 `<data_dir>/capsules/<filename>`。文件存在时，AgentCompass 只校验 SHA-256，不访问网络也不改写文件；文件不存在时，先下载到同目录临时文件，校验预定义摘要后原子重命名。

新增社区 Capsule 需要提交 AgentCompass registry 变更。发布物还应提供签名、SBOM、构建 provenance 和依赖许可证。

## 与 `repair_glibc` 的关系

配置 setup Capsule 后，Claude Code、Codex 和 OpenHands 都不会调用 `repair_glibc`，Capsule 失败时也不静默回退。Legacy repair 只保留在现有非 Capsule 路径中。

每个 Environment 使用一个满足该安装流程依赖的 Capsule。复合工具链作为单个产物构建，不在目标环境中组合多个 Capsule。