> ## 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 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 ```text theme={"system"} 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: ```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" } } ``` 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//`, 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: ```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 ``` 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: ```json theme={"system"} { "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: ```json theme={"system"} { "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 `/capsules/` 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.