Runtime Capsules

A Runtime Capsule is a generic, immutable toolchain closure injected before harness setup. It provides stable runtimes such as Node/npm or Python/pip without containing or identifying a harness. The harness version still belongs to its existing install_command or openhands_version setting.

AgentCompass currently registers node24-v1 for Claude Code and Codex, python312-v1 for OpenHands, and python312-node24-v1 for installation flows that need Python 3.12, Node 24, and uv in a single Capsule.

Lifecycle

setup_capsule_tag
        │
        ▼
Check whether an installed harness can be reused
        │ Installation needed
        ▼
Probe target OS, architecture, and libc family
        │
        ▼
Resolve the predefined filename, SHA-256, URL, and target variant
        │
        ▼
Verify/download the bundle and install its immutable runtime closure
        │
        ▼
Run the original install_strategy with the Capsule package manager
        │
        ▼
Seal only the harness-owned setup tree, then run the harness on the original /

A Capsule does not replace preinstalled, install_if_missing, or upload. Codex and Claude Code skip Capsules for preinstalled and when install_if_missing finds an existing harness. When setup_capsule_tag is unset, they continue using the original installation method.

Bundle contract

A v1 bundle is a gzip tar with agentcompass-capsule.json at its root. Its distributed filename and digest are defined by the built-in registry:

{
  "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"
  }
}

The manifest contains no harness id, harness version, or harness entrypoint. Newly built Node/Python runtimes match platform.libc. A bundle can carry private glibc and musl libraries to launch separate ELF executables using either ABI; this does not let a glibc process load musl native extensions or vice versa.

AgentCompass validates the digest, platform, archive paths, and required tools, then atomically installs the closure under /tmp/agentcompass-capsules/. Harness packages are installed under /tmp/agentcompass-capsule-setups/<bundle-sha256>/, a writable root derived only from Capsule content. The Capsule itself remains immutable.

Activation and compatibility

Capsules do not use bubblewrap, chroot, a replacement rootfs, mount namespaces, or a command bridge. The benchmark image remains /, so the harness has the same filesystem, devices, network, cwd, and process capabilities it would have when launched natively.

The Capsule launcher adds its toolchain to PATH only during setup. The final harness process is started by absolute path without exporting the Capsule PATH, npm prefix, or a global LD_LIBRARY_PATH. Consequently shell and tool subprocesses resolve the benchmark image’s commands and dependencies. OpenHands also removes its setup-only PYTHONPATH entry after importing the harness modules.

After package installation, seal-tree examines only the AgentCompass-owned setup root. It rewrites Node/Python/bash shebangs to private runtime paths. For an ELF executable with an interpreter, it assigns the matching private loader and RPATH only when the existing loader cannot load it. For shared libraries and native extensions, it appends the matching private library paths to RPATH. Each current bundle includes private glibc and musl ABI support because one npm package can contain both families. No target system library or global linker configuration is changed.

Public Python entrypoints use a wrapper that executes the actual interpreter so uv/venv record the correct interpreter directory and standard library location. Install scripts may execute newly downloaded native programs, and tools may install dependencies at runtime. A seal-tree invocation before or after those operations does not automatically cover them; validate them in the corresponding installation flow.

This mechanism handles missing or old userspace runtimes; it cannot emulate CPU instructions, kernel syscalls, seccomp permissions, executable mounts, or another architecture. Those conditions fail normally instead of falling back to repair_glibc.

The npm bundled with Node 24 restricts lifecycle scripts for unapproved dependencies. Claude Code and Codex setup explicitly enables the traditional script behavior for the user-configured harness install. Point install_command only at trusted packages.

Build Capsules

The builder supports Docker and Podman. Select one with --container-cli docker or --container-cli podman; Docker is the default. The existing --docker option remains a compatible alias. Build one immutable artifact for each target libc profile:

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

The defaults pin Node.js 24.19.0 with npm 11.17.0 and Python 3.12.10 with pip. Use --node-version 24.x.y or --python-version 3.12.x for another exact runtime release. The current builder emits Linux x86_64 bundles.

The combined Capsule also supplies uv/uvx, pinning uv 0.12.10 by default; use --uv-version to change it. Python, Node, and the package managers belong to one bundle for installation flows that require both toolchains. It does not include Chromium or every tool plugin’s dependencies.

This feature is still under development and has not been merged. Development builds keep the existing v1 tags and distribution filenames, replacing earlier artifacts and updating their registered SHA-256 digests. Replace any corresponding old files in the host cache as well; digest validation remains strict.

Use Capsules with harnesses

Codex example:

{
  "install_strategy": "install_if_missing",
  "install_command": "npm install -g @openai/codex",
  "setup_capsule_tag": "node24-v1"
}

Claude Code uses the same setup_capsule_tag. Changing the harness version changes only install_command, not the Capsule tag.

OpenHands uses the Python Capsule:

{
  "openhands_version": "1.23.0",
  "setup_capsule_tag": "python312-v1"
}

With this tag, OpenHands installs its SDK/tools with Capsule pip instead of downloading micromamba.

Capsules supply toolchains, not harness packages. install_if_missing still needs package-registry access from the Environment. Offline environments should provide a registry cache, an offline install_command, preinstalled, or upload.

Hermes’s bare AIAgent does not reproduce the full CLI’s configuration, tool initialization, and session behavior. To assess installation coverage, install the official CLI dependencies and use an official execution entrypoint. Local browser tools can still need Node/npx, Chromium, and system libraries when the TUI is omitted. A working Python loop does not establish that the full toolset is available.

Distribution and cache

AgentCompass defines each supported logical tag and all of its target variants with distribution filenames, SHA-256 digests, and download URLs. Users select only the logical tag; arbitrary local paths, URLs, and OCI references are not accepted.

Bundles are stored at <data_dir>/capsules/<filename> on the controller. If a file exists, AgentCompass verifies its SHA-256 without network access or rewriting it. If absent, AgentCompass downloads to a temporary file in the same directory, verifies the predefined digest, and atomically renames it.

Adding a community Capsule requires an AgentCompass registry change. Releases should also provide signatures, an SBOM, build provenance, and dependency licenses.

Relationship to repair_glibc

Claude Code, Codex, and OpenHands never call repair_glibc when a setup Capsule is configured and do not silently fall back after Capsule failure. Legacy repair remains only on existing non-Capsule paths.

Use one Capsule per Environment with the toolchains needed by that installation flow. Build combined toolchains as one artifact instead of composing multiple Capsules in the target environment.