Releases and upgrades

Releases and upgrades

This page covers what a ForgeGuard release means for a consumer of the artifacts — which tag to pin, how to upgrade, and how to roll back. The release automation internals live in the maintainer documentation and are not needed to operate a deployment.

Release and version scheme

ForgeGuard releases are tagged <upstream-base>-forgeguard.<n>, for example v2026.7.1-forgeguard.5:

• <upstream-base> is the upstream NousResearch/hermes-agent release tag this fork’s main is synced to (recorded in the FORK_UPSTREAM_BASE marker at the repository root).
• <n> increments per base tag across fork releases.

Each release title and notes also surface the actual Hermes Agent product version (from pyproject.toml), since the fork tag says which upstream release line it tracks, not which product version it contains. See Compatibility for the current mapping.

Image tags to use

Tag	Mutability	Use
runtime-<version> / cli-<version>	immutable	Pin a deployment to a specific fork release.
runtime-<git-sha> / cli-<git-sha>	immutable	Trace an image back to its exact commit.
runtime-latest / cli-latest	rolling	Testing / always-newest; drifts on every fork release.

For any durable deployment, pin an immutable *-<version> tag. The *-latest tags are convenient for testing but are not immutable and move forward without notice. See Image tag families for full detail.

Prerequisites

• A runtime deployment with external state on ~/.hermes.
• A backup of that state taken before upgrading.

Upgrade

Because the image is immutable and state lives on the volume, upgrading is: pull the new tag, remove the old container, recreate against the same state.

# 1. Back up first (see Persistence and backups).
# 2. Pull the target release.
docker pull ghcr.io/forgeguard-ai/hermes-agent:runtime-<new-release>

# 3. Recreate the container against the same ~/.hermes.
docker rm -f hermes
docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  -e HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin \
  -e HERMES_DASHBOARD_BASIC_AUTH_PASSWORD="<from your secret store>" \
  -e HERMES_DASHBOARD_BASIC_AUTH_SECRET="<stable secret>" \
  ghcr.io/forgeguard-ai/hermes-agent:runtime-<new-release> gateway run

Verify

curl --fail http://localhost:9119/api/status
docker inspect --format '{{.State.Health.Status}}' hermes

The dashboard should return to healthy and your profiles/sessions should be intact.

Roll back

Because the previous immutable tag still exists and your state is external, rolling back is the same procedure with the old tag — after restoring the pre-upgrade backup if the newer version migrated state in place:

docker rm -f hermes
# (restore ~/.hermes from backup if needed)
docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data -p 9119:9119 \
  ghcr.io/forgeguard-ai/hermes-agent:runtime-<previous-release> gateway run

Read release notes before upgrading across an upstream base bump — a change in <upstream-base> can carry upstream behaviour changes that affect state.

macOS desktop installer note

Desktop .dmg/.zip builds are ad-hoc signed and not notarized; after installing, run xattr -cr /Applications/Hermes.app once. See Desktop artifacts.

Related

• Image tag families
• Persistence and backups
• Compatibility