Skip to content

runtime-image.md

Latest commit

 

History

History
153 lines (121 loc) · 6.86 KB

runtime-image.md

File metadata and controls

153 lines (121 loc) · 6.86 KB
Raw

Published worker image

The Hermes Helmet worker runs from a Docker image. The host helmet CLI and Captain skills are a separate installation: pip install does not pull GHCR and does not start or restart the worker.

Current stable pin

Use the digest, not a mutable tag:

ghcr.io/machinewisdomai/hermes-helmet/runtime@sha256:04f772b48151813aec165ec81ee7323e316cababa686963fbc4064a40b283c2b
Field Value
Tag 1.0.0 (the tag preserves the tested index digest; use the digest)
Source commit 24876c7583f5dd3219e94e27b72a8952ba9752aa
Platforms linux/amd64, linux/arm64
Publication workflow GitHub Actions run 39936683445
Release Hermes Helmet 1.0.0

This image is the runtime image of the Hermes Helmet 1.0.0 stable release, built from the source commit above. It is separate from the release's wheel, source distribution and plugin archive, which are GitHub release assets (the release is not a PyPI publication). Publication does not install or restart any worker. The release's differential scan passed the maintained policy; that does not claim the upstream base has zero known vulnerabilities.

The digest identifies the image built from that recorded source SHA. /opt/hermes-helmet/SOURCE_COMMIT inside the container is that SHA.

This image bundles Claude Code 2.1.286 and the Claude subscription model-provider plugin on Hermes Agent 0.21.6. It supports the published-image route for Claude subscription workers.

Run the published image

From a clone of this repository, after deploy/.env holds the worker token and HERMES_HELMET_IMAGE is set to the digest above. Compose interpolates image: from that file. A leftover shell export of HERMES_HELMET_IMAGE overrides .env; docker pull "$HERMES_HELMET_IMAGE" does not read .env. If this shell previously exported the variable, unset it so .env wins, then pull and start through Compose:

unset HERMES_HELMET_IMAGE
docker compose --env-file deploy/.env -f deploy/compose.yaml pull hermes
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d --no-build
docker compose --env-file deploy/.env -f deploy/compose.yaml exec hermes \
  cat /opt/hermes-helmet/SOURCE_COMMIT

--no-build is the normal runtime path. Compose still knows how to build from deploy/Dockerfile; that path is for development, below.

deploy/compose.yaml defaults image to hermes-helmet:local when HERMES_HELMET_IMAGE is unset in both the shell and deploy/.env. Leave that default for local builds, or set HERMES_HELMET_IMAGE=hermes-helmet:local explicitly. Do not point it at latest or main.

The image entrypoint writes the worker token to an owner-only file on tmpfs, copies the mounted policy into /opt/data/github-issue-poller/policy.json, removes GH_TOKEN and GITHUB_TOKEN, then starts upstream Hermes. See the quickstart for checkout, profile login, and poller install, and private-overlay.md to keep company configuration in a separate repository.

Development build

To wrap the same deploy/Dockerfile around a local checkout, select hermes-helmet:local explicitly. Unsetting the shell variable is not enough when deploy/.env still pins the published digest:

export HERMES_HELMET_SOURCE_COMMIT="$(git rev-parse HEAD)"
export HERMES_HELMET_IMAGE=hermes-helmet:local
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d --build
docker compose --env-file deploy/.env -f deploy/compose.yaml exec hermes \
  cat /opt/hermes-helmet/SOURCE_COMMIT

SOURCE_COMMIT should match git rev-parse HEAD of the tree you built. scripts/build-dev-image.sh and scripts/smoke-dev-image.sh are the same development path without Compose.

The Dockerfile still pins the upstream Hermes Agent base nousresearch/hermes-agent:v0.21.6@sha256:55e192fba0cd4fde61142abbff5adeacff40efdb482ccd0ff877924bd274f909. Override only with another immutable tag+digest.

Change the pin or roll back

Pause new intake before replacing the image. Removing the policy dispatch_label from open issues stops new issue dispatch; it does not pause the review-repair poller. Use the Hermes cron pause/resume interface on the existing github-issue-poller job. Leave the worker running so queued or running tasks can finish or be explicitly reconciled. Recording a blocker does not cancel a task.

  1. Discover the job, then pause it:

    docker compose --env-file deploy/.env -f deploy/compose.yaml exec hermes \
  /opt/hermes/.venv/bin/hermes cron list
docker compose --env-file deploy/.env -f deploy/compose.yaml exec hermes \
  /opt/hermes/.venv/bin/hermes cron pause github-issue-poller

  2. Leave the worker running. Let queued and running implementation or repair tasks finish, or reconcile them explicitly. Keep the named volume and the existing issue/task/PR associations.

  3. Set HERMES_HELMET_IMAGE in deploy/.env to the new digest (or the previous digest to roll back). If this shell still exports an older value, unset it so .env wins:

    unset HERMES_HELMET_IMAGE
docker compose --env-file deploy/.env -f deploy/compose.yaml pull hermes
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d --no-build

  4. Confirm /opt/hermes-helmet/SOURCE_COMMIT matches the source commit you intended.

  5. Resume the same job and check its state:

    docker compose --env-file deploy/.env -f deploy/compose.yaml exec hermes \
  /opt/hermes/.venv/bin/hermes cron resume github-issue-poller
docker compose --env-file deploy/.env -f deploy/compose.yaml exec hermes \
  /opt/hermes/.venv/bin/hermes cron list

Keep the same named volume (hermes_helmet_state in the public Compose file, or the company volume in a private overlay). Worker configuration, credentials, checkouts, the poller ledger, and issue/task/PR associations live under /opt/data. Replacing the image does not replace that volume.

Reconcile active work before changing repositories[].slug or repositories[].worktree. Those mappings are how the poller finds checkouts and existing assignments; moving them under a running intake can attach new work to the wrong tree.

The 1.0.0 image was published by the workflow run linked above and is tagged ghcr.io/machinewisdomai/hermes-helmet/runtime:1.0.0. The repository's preview-runtime-image.yml workflow still exists: it builds and scans both platforms, and its manual workflow_dispatch publication, run from protected main with a full commit SHA, tags ghcr.io/machinewisdomai/hermes-helmet/runtime:preview-<full-sha> and does not promote latest or stable. Earlier preview images were published that way. Pin by digest in every case. See SECURITY.md for scan and visibility notes.