This page covers what the image pins, how pins are updated, which release tag to pull and how to verify a release.
- Pinned inputs
- Agents do not update themselves
- Scheduled updates
- Releases
- Verifying a release before use
- Upstream publisher verification
- Optional extras
- Documented installs
versions.env pins every input of the main image (Containerfile): the base image digest, the apt snapshot date, each agent and tool version, and the checksum of every download. The build checks each download against it. The one exception is the Rust toolchain: rustup-init downloads the components and checks each against the hashes in Rust's own channel manifest. The Kelos variant keeps its pins in Containerfile.kelos.
Node.js is the official Linux tarball from nodejs.org, installed in /opt/node with node, npm and npx linked into /usr/local/bin. versions.env pins NODE_VERSION and the two Linux checksums (NODE_SHA256_AMD64, NODE_SHA256_ARM64), and the scheduled update follows the 26.x line. The image removes include/, share/, README.md and CHANGELOG.md from the install. Verification happens in two places: the updater checks the GPG signature on Node.js's checksum list before it writes the pins (Node.js release keyring), and the build checks the downloaded tarball against the pinned SHA-256 (build/install-tool.sh).
Claude Code is the native binary from Anthropic's release host, the file Anthropic's native installer downloads. The scheduled update checks the release's manifest.json against Anthropic's GPG signature before it pins the binary's SHA-256 (binary integrity).
gosec, gitleaks and the ContainerSSH guest agent (containerssh-agent) are upstream release archives. The build checks each against the SHA-256 in the project's published *_checksums.txt (GOSEC_, GITLEAKS_ and CONTAINERSSH_AGENT_ pins). The image installs the agent at /usr/local/bin/containerssh-agent and links it at /usr/bin/containerssh-agent, ContainerSSH's default agentPath (AgentPath default in config/kubernetes.go at ContainerSSH v0.6.0). The updater takes these three tools' hashes only from the release's gosec_<version>_checksums.txt, gitleaks_<version>_checksums.txt and agent_<version>_checksums.txt, and refuses a release that lacks the file.
The agent version follows the ContainerSSH server image. CONTAINERSSH_AGENT_SERIES in scripts/bump_versions.py maps the server's tag series (v0.6) to the agent minor series tested with it (0.11), and the updater only proposes newer patch releases in that series. If the server tag has no entry, the updater keeps the current agent pin and prints why. The v0.6 tag's digest can move between patch releases, so a mapping change needs a review of the verified pair of server digest and agent version. The verified pair is the server docker.io/containerssh/containerssh:v0.6@sha256:f6b195c221739b0f1a43c567bc9df0a0f3b3bd92ccc25ef451e6d4122820c13b (CONTAINERSSH_IMAGE) with containerssh-agent 0.11.0 (CONTAINERSSH_AGENT_VERSION). On 2026-11-04 SFTP, ssh -L and ssh -D worked with this pair in a cluster, in persistent mode with disableAgent: true. VERIFIED_CONTAINERSSH_PAIR in scripts/bump_versions.py records this pair, and test_pinned_containerssh_pair_is_the_cluster_verified_pair fails when versions.env pins a different server image reference (name, tag or digest) or agent version. A pull request from the scheduled update that changes either pin therefore fails CI until someone re-runs the SFTP, ssh -L and ssh -D check from docs/kubernetes.md against the new pair and updates the constant and this paragraph. Do not merge a guest agent or server update before that check. The test runs in the build workflow on the pull request, not in the bump job, so the pull request still opens and shows the failure. That day Docker Hub's v0.6 tag resolved to this digest, v0.6.1 resolved to a different digest, and no v0.6.0 tag existed.
Each tool is built in its own stage, so an update downloads only the layers that changed:
| Condition | Effect on layer digests |
|---|---|
Release build, tool unchanged, same BuildKit (BUILDKIT_IMAGE) |
Byte-identical to the previous release's layer. File times later than SOURCE_DATE_EPOCH are set to it (BuildKit's rewrite-timestamp option). |
| Release that updates BuildKit | Every layer's digest can change |
scripts/build.sh with Podman 5.6 or later |
Same as a release build |
scripts/build.sh with an older Podman server |
The script leaves the options out and prints a warning. The image works the same, but every layer gets a new digest. |
/etc/agentainer/versions.json in the image lists every pin and every installed apt package version, and an apt_source field that says where apt got them.
APT_SNAPSHOT pins every apt package to one day of snapshot.ubuntu.com. When that service fails, a build made through scripts/build.sh falls back to archive.ubuntu.com as it is that day, so a build does not stop on someone else's outage. Every build in build.yml except the release publish job goes through that script: pull request builds, pushes to develop and main, and local builds. The publish job builds with docker/build-push-action from the versions.env pins and never falls back.
A fallback build records itself in three places:
/usr/local/share/agentainer/apt-sourceholds one line,archive-fallback <UTC date> (snapshot <APT_SNAPSHOT> unavailable). A snapshot build holdssnapshot <APT_SNAPSHOT>./etc/agentainer/versions.jsonhas the same line inapt_source.- The build report in the job summary prints a
WARNINGline, and the image job adds a warning annotation to the run.
A fallback image is not reproducible and cannot be released. Two checks keep a fallback from reaching a release:
scripts/check-release-platform.shfails thepublishjob unless the pushed image'sapt-sourceis exactlysnapshot <APT_SNAPSHOT>with the pin fromversions.env.scripts/check-apt-fallback.shfails the image job when the build fell back and the change modifiesAPT_SNAPSHOTinversions.envorbuild/apt-packages.txt, because a release would install those inputs from the snapshot and the fallback build did not test them. A fallback with other changes only warns. Without a base commit to compare with (a manual run, for example), it only warns.
For a local build, the fallback is the default. To make a build fail when the snapshot is unavailable, run scripts/build.sh --strict-apt or set APT_FALLBACK= (empty) in the environment. The Containerfile enables the fallback only for the value archive. build/apt-install.sh does the install.
The engine caches the apt layer. After a fallback build, a later default local build can reuse that layer even when the snapshot works again, and the image keeps recording the fallback. build.sh prints a warning in that case. To try the snapshot again, run scripts/build.sh --no-cache, which passes --no-cache to the engine's build (podman build --help and docker build --help list it), or run --strict-apt, whose build argument differs and so misses the cached layer.
versions.env also pins the optional extras, which the image carries as lockfiles but does not install (Optional extras).
| Agent | Setting |
|---|---|
| Claude Code | DISABLE_UPDATES=1 (env vars) |
| Codex | /etc/codex/requirements.toml (managed configuration) |
| Antigravity | AGY_CLI_DISABLE_AUTO_UPDATE=true (troubleshooting) |
| OpenCode | "update": "disable" in its global config, ~/.config/opencode/opencode.json (config; OpenCode ignores the setting in project config). The image also sets OPENCODE_DISABLE_AUTOUPDATE=1, which OpenCode's v1 CLI docs name; the v2 docs do not, and whether 2.2.5 honors it is not verified. |
New versions arrive only with a new image.
On the 1st and 15th of each month at 06:00 UTC, .github/workflows/bump.yml resolves the newest upstream versions with scripts/bump_versions.py and opens a pull request against develop. It refuses to write any value that does not match the expected format for its pin. The pull request's build page shows which pins changed. A maintainer reviews and merges it by hand, and nothing is published until the next release.
An update PR lists increases to the leading number of a three-part tool version under "Major-version upgrades" and asks the maintainer to acknowledge the compatibility review in its description. CI does not enforce that checkbox. Minor updates to tools below 1.0 can also break compatibility, so review their upstream notes as well (Semantic Versioning).
The resolver follows current upstream release pointers with no minimum release age, except for the optional extras (Optional extras). Proposed binaries run in build and test jobs before anyone reviews the pull request. Checksums and publisher signatures establish byte identity and the signing identity, not that the code is safe, so review upstream changes before merging.
Run the same workflow manually through its workflow_dispatch trigger for an urgent security fix or an upstream change that breaks an agent. GitHub documents scheduled and manual triggers.
The workflow opens the pull request with a GitHub App token when the repository has both the variable BUMP_APP_CLIENT_ID and the secret BUMP_APP_PRIVATE_KEY; CI then starts on its own. Otherwise it uses GITHUB_TOKEN, and GitHub holds the pull request's CI until a maintainer chooses "Approve workflows to run" (CONTRIBUTING.md describes the App).
Releases use Semantic Versioning:
- Stable versions have the form
MAJOR.MINOR.PATCH, such as0.1.0. - Development prereleases use the next intended version followed by
-dev.YYYYMMDD.N, such as0.1.0-dev.20261019.1. The date must exist, and the build number starts at 1 and increments for another build that day. - The parser also accepts other SemVer prerelease identifiers, such as
0.1.0-rc.1. - Container tags exclude SemVer build metadata (
+...) and are limited to 128 characters (distribution tag format).
Versions below 1.0.0 are initial development, without a stable compatibility promise. Agentainer's public interfaces are its launcher commands, documented environment variables, configuration paths and persistent-home upgrade behavior. Bundled tool versions remain separate in versions.env.
Each release publishes ghcr.io/chadmayfield/agentainer for amd64 and arm64:
- tagged with the version and
sha-<commit>, withlatestreserved for stable releases; - signed with cosign keyless signing, the index and each architecture's image;
- with an SBOM and BuildKit provenance for each architecture, a signed GitHub provenance attestation for the multi-architecture index, and zstd-compressed layers.
A release requires a maintainer-signed tag on a release merge in main; a branch merge alone does not publish. CONTRIBUTING.md describes the release procedure, the checks before publication and how latest moves.
Pull an explicit version tag. Prereleases never move latest, so before the first stable release there is no latest tag:
podman pull ghcr.io/chadmayfield/agentainer:0.1.0-dev.20261024.1
AGENTAINER_IMAGE=ghcr.io/chadmayfield/agentainer:0.1.0-dev.20261024.1 bin/agentainer upA version exists only after its release workflow completes. A merge to develop runs CI and does not publish an image. To use features merged after the newest release tag, build the image locally with scripts/build.sh.
A runtime needs zstd support to pull the image:
| Runtime | First version that pulls zstd layers |
|---|---|
| Docker Engine | 23.0.0 ("Add support for pulling zstd compressed layers", Engine 23.0 release notes, moby/moby#41759) |
| containerd, including Kubernetes nodes that use it | 1.5.0 ("Add support for layers compressed with zstd", containerd v1.5.0 release notes) |
| Podman | Not verified. Podman's release notes do not name a version. containers/image added zstd in containers/image#639, and Podman 1.6.2 is the first release whose go.mod uses a containers/image version with that change. |
The release workflow for v0.1.0-dev.20261019.1 completed signing, attestation storage and registry verification. Each later release must pass the same checks for its own digest.
Use a trusted checkout of this repository and independently installed Docker Buildx, cosign and GitHub CLI. Verify the maintainer-signed release tag with the trusted public key and fingerprint first. Obtain the full source commit from that tag and the image index digest from the registry. Review the digest before running the verifier; never substitute an unverified mutable tag afterward.
set -eu
version=0.1.0-dev.20261024.1
git verify-tag "v$version"
commit=$(git rev-parse "v$version^{commit}")
# Replace this placeholder with the release's full index digest.
digest=sha256:REPLACE_WITH_64_HEX_DIGITS
python3 tests/host/test-published-image.py ghcr.io/chadmayfield/agentainer "$digest" \
"https://github.com/chadmayfield/agentainer/.github/workflows/build.yml@refs/tags/v$version" \
https://token.actions.githubusercontent.com chadmayfield/agentainer "$commit" "refs/tags/v$version"
AGENTAINER_IMAGE="ghcr.io/chadmayfield/agentainer@$digest" bin/agentainer upThe verifier checks:
- Index and platform signatures against the exact workflow identity for the release tag and the GitHub OIDC issuer (Sigstore CI verification).
- GitHub provenance against the repository, source commit, tag ref and workflow identity, rejecting self-hosted runners (GitHub verification flags).
- Both platforms' BuildKit provenance against the expected source repository and commit. A dirty or different revision fails (BuildKit provenance fields).
- SBOM and provenance descriptors bound to each platform manifest, then a pull and native startup by the verified index digest (attestation storage).
It pulls and starts the verified digest, so run it only where you intend to run that release. It needs registry access and GitHub authentication. It does not establish a SLSA level or validate every SBOM package entry. Its commands and flags are in the verifier source. The launcher does not perform these checks.
The updater requires gh, cosign and GnuPG in addition to Python. The scheduled workflow installs cosign through its pinned installer action. scripts/verify_upstream.py checks supported publishers before the resolver writes any pins. A missing verification tool, missing signing asset, changed checksum or failed signature stops the update. Build downloads still check their pinned hashes. The optional extras are the exception: a failed check keeps only that extra's pin (Optional extras).
| Download | Required publisher check |
|---|---|
| GitHub CLI | GitHub provenance from cli/cli, workflow deployment.yml on refs/heads/trunk. |
| uv | GitHub provenance from astral-sh/uv, workflow release.yml on refs/heads/main. |
| Ruff | GitHub provenance from astral-sh/ruff, workflow release.yml on refs/heads/main. |
| golangci-lint | GitHub provenance from golangci/golangci-lint, workflow release.yml at the selected release tag. |
| yq | Signed BSD checksum list from mikefarah/yq, workflow release.yml at the selected release tag. |
| Trivy binary | Signed checksum list from aquasecurity/trivy, workflow reusable-release.yaml at the selected release tag. |
| Codex package | Sigstore bundle for the whole package from openai/codex, workflow rust-release.yml at the selected release tag. |
| Claude Code | GPG-signed release manifest with the pinned Anthropic key fingerprint. |
| Node.js | GPG-signed SHASUMS256.txt by one of the release keys in scripts/keys/nodejs-release-keys.asc. |
| AWS CLI | GPG signature (<zip>.sig) on each installer zip, by the AWS CLI Team key in scripts/keys/aws-cli-public-key.asc with the fingerprint pinned in the updater. AWS publishes no checksums, so the updater computes the SHA-256 pins from the verified zips. |
| Optional extras (npm) | npm registry signature on every lockfile entry, by a key in scripts/keys/npm-registry-keys.json (Optional extras). |
| gosec | Checksum verified; publisher signature not verified. The SHA-256 comes from gosec_<version>_checksums.txt. |
| gitleaks | Checksum verified; publisher signature not verified. The SHA-256 comes from gitleaks_<version>_checksums.txt. |
| ContainerSSH guest agent | Checksum verified; publisher signature not verified. The SHA-256 comes from agent_<version>_checksums.txt. |
GitHub provenance checks require the exact workflow certificate identity, repository, source ref and GitHub OIDC issuer (GitHub CLI verification, CLI release workflow, uv release workflow, Ruff release workflow, golangci-lint release workflow). Sigstore bundle checks require the exact workflow certificate identity and GitHub OIDC issuer (cosign blob verification, yq signing workflow, Trivy signing workflow, Codex signing action).
The updater does not check publisher signatures for Go, Rust, abtop, gosec, gitleaks, the ContainerSSH guest agent, tea, kubectl, Helm, Antigravity, OpenCode or the pinned container images. Their checksum, package-manager and digest checks remain. Some of these projects publish signing material; their trust policies need separate review before the updater enforces them. No unsigned-update fallback exists for the publishers in the table.
The updater takes the newest stable v26.x.y from https://nodejs.org/dist/index.json. It checks that version's SHASUMS256.txt.sig with gpg against the keyring in scripts/keys/nodejs-release-keys.asc. A signature from any one of the eight active releasers' keys passes. The updater then reads the two Linux checksums from the verified file.
A failed Node.js check stops the whole scheduled update. main() in scripts/bump_versions.py returns 1 on any LookupFailed and writes no pins, for every tool. This happens when the key that signed the release has expired or been revoked (EXPKEYSIG or REVKEYSIG in GnuPG's status output, with the message "the pinned signing key needs a hand update") and when a release is signed by a key that is not in the keyring. Updates for all tools resume only after a maintainer refreshes the keyring by hand.
The keyring comes from nodejs/release-keys, at commit 481637f813e912c4aa3622d7964ab426c97b8e8d. Node.js lists the active releasers in its release keys section. The scheduled update never changes these files. Refresh the keyring in its own pull request:
- At the new
nodejs/release-keyscommit, take the fingerprints listed between the<!-- Active releasers keys -->markers in its README. - Download each
keys/<FINGERPRINT>.ascat that commit. - Import the files into a temporary
GNUPGHOME. - Write
scripts/keys/nodejs-release-keys.ascwithgpg --armor --export <the fingerprints>. Do not concatenate the downloaded files. At least one of them has no trailing newline, and plain concatenation silently drops a key. - Set
NODE_KEY_FINGERPRINTSand the commit in its comment inscripts/bump_versions.py. - Update the commit and the expiry dates in this section.
- Run the unit tests.
test_node_keyring_holds_exactly_the_pinned_fingerprintschecks the keyring file against the constant.
Expiry dates of the eight keys in the current keyring, read with gpg --list-keys from a temporary GNUPGHOME:
| Releaser | Expires |
|---|---|
| Rafael Gonzaga | 2027-06-04 (primary key) |
| Ulises Gascón | 2027-07-18 (signing subkey); 2028-06-01 (primary key) |
| Stewart X Addison | 2028-06-28 |
| Marco Ippolito | 2034-03-26 |
| Ruy Adorno | none |
| Antoine du Hamel | none |
| Richard Lau | none |
| Juan José Arboleda | none |
Refresh the keyring before the earliest date.
The updater takes the first version heading of the AWS CLI v2 changelog, https://raw.githubusercontent.com/aws/aws-cli/v2/CHANGELOG.rst, which AWS links as the list of versions (installing past releases). For each architecture it downloads awscli-exe-linux-<x86_64|aarch64>-<version>.zip and its .sig from https://awscli.amazonaws.com and checks the signature with gpg against scripts/keys/aws-cli-public-key.asc. AWS publishes no checksum for the zips, so the updater computes the SHA-256 pins only after both signatures pass. When the newest version equals AWSCLI_VERSION, the updater downloads nothing and keeps the pins.
A failed AWS CLI check stops the whole scheduled update. main() returns 1 and writes no pins, for every tool, as for Node.js.
AWS publishes the key as text in the AWS CLI install guide, not as a file to download. The file is a copy of that block. The guide lists the key as AWS CLI Team <aws-cli@amazon.com>, fingerprint FB5D B77F D5C1 18B8 0511 ADA8 A631 0ACC 4672 475C, expiring 2027-07-01. test_aws_cli_key_holds_exactly_the_pinned_fingerprint checks the file against AWSCLI_KEY_FINGERPRINT in scripts/bump_versions.py.
After 2027-07-01, GnuPG reports EXPKEYSIG for a release signed with this key, with the message "the pinned signing key needs a hand update". The signature check fails and the scheduled update stops for all tools until a maintainer refreshes scripts/keys/aws-cli-public-key.asc from the install guide. To refresh it, copy the key block from the guide into the file, set AWSCLI_KEY_FINGERPRINT if the fingerprint changed, update the expiry date here, and run the unit tests.
Refresh the key before 2027-07-01.
versions.env pins three npm tools that agentainer-extras install adds on request (Optional extras):
| Pin | npm package | Catalog directory |
|---|---|---|
KANDEV_VERSION |
kandev |
kandev |
OPENCHAMBER_VERSION |
@openchamber/web |
openchamber |
REA_VERSION |
rea-agents |
rea |
Each catalog directory, under rootfs/usr/local/share/agentainer/extras/, holds a package.json that depends on exactly the pinned version and a package-lock.json with an integrity hash for every package in the tree. The version in package.json must equal the versions.env pin, and tests/host/test-extras-catalog.sh checks this in CI.
For each extra, scripts/bump_versions.py:
- Picks the newest stable, non-deprecated version, no newer than the
latestdist-tag, whose publish time in the registry'stimefield is at least 7 days old. When that version is not newer than the pin, the pin and the catalog files stay as they are. - Regenerates the lockfile with
npm install --package-lock-only --ignore-scripts --before=<now minus 7 days>, so every dependency in the tree is also at least 7 days old (npmbefore). It uses an empty npm user config and the public registry. - Fails the extra when the new lockfile has a package with an install script (
hasInstallScript, package-lock.json) that the committed lockfile did not have, unless the package isnode-ptyorfrida.agentainer-extrasinstalls with--ignore-scripts, so no install script runs; this check reports a change in the tree for review. - Checks every lockfile entry against the registry. The entry must resolve from
https://registry.npmjs.org/, itsintegritymust equal the registry'sdist.integrityfor that version, and one of the version'sdist.signaturesmust verify withopensslover<name>@<version>:<integrity>with an ECDSA P-256 key inscripts/keys/npm-registry-keys.json(npm registry signatures). A key with anexpirestime counts only for a version published before that time. A signature by an unknown key does not count. Bundled entries are covered by their parent's integrity; alinkentry fails.
A failed check for one extra, including a missing npm or openssl, keeps that extra's pin and catalog files and does not stop the run. The other pins still update. bump_versions.py --failures FILE writes one line per failed extra to FILE. In the scheduled workflow, the extras-failures job prints those lines in the run summary and fails the run after the pull request for the other pins is open.
The pull request job applies the resolver's patch only when it modifies versions.env, deploy/kubernetes/*/deployment.yaml, deploy/kubernetes/agentainer/statefulset.yaml (the FILEBROWSER_IMAGE pin) or an extras package.json or package-lock.json, and creates, deletes or renames no file (.github/actions/bump-pr/action.yml).
CI's lint-unit job runs tests/host/test-extras-catalog.sh and scans the extras lockfiles with Trivy, using the TRIVY_SCANNER_IMAGE pin. The scan is report only: findings go to the job's step summary and never fail the job.
scripts/keys/npm-registry-keys.json is a copy of https://registry.npmjs.org/-/npm/v1/keys. It holds two keys: SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA, which expired on 2025-01-29, and SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U, with no expiry. The scheduled update never changes this file. A signature by a key that is not in the file fails that extra's update until a maintainer refreshes the file in its own pull request:
- Download
https://registry.npmjs.org/-/npm/v1/keys. - Replace
scripts/keys/npm-registry-keys.jsonwith the downloaded document, unchanged. Every key must havekeytypeandschemeecdsa-sha2-nistp256;bump_versions.pyrefuses any other. - Update the date in the comment above
NPM_KEYSinscripts/bump_versions.pyand the key list in this section. - Update the key IDs and expiry times in
test_registry_keys_file_pins_both_npm_keysintests/unit/test_bump_versions.py, then run the unit tests.
These tools are not in the image. The docs give a version-pinned install command for each. They are manual pins: the scheduled update does not track them, and no check fails when upstream publishes a newer release. The last column records when each pin was last compared with upstream.
| Tool | Pinned version | Install | Integrity check | Last checked |
|---|---|---|---|---|
| MarkItDown | 0.1.9 | uv tool install "markitdown[...]==0.1.9" (project tools) |
uv's PyPI download. No hash pin. | 2026-11-04: the newest release on PyPI |
| pandoc | 3.13 | Static tarball into ~/.local/bin (project tools) |
SHA-256 from GitHub's release asset digests, checked with sha256sum -c. Publisher signature not verified. |
2026-11-04: the newest release |