Skip to content

    Development documentation — this describes the current development branch. Documented behavior may not exist in the latest release.

    ForgeGuard changes

    ForgeGuard changes

    Section titled “ForgeGuard changes”

    ForgeGuard maintains a distribution of upstream NousResearch/hermes-agent. It tracks upstream tagged releases and adds a packaging and release overlay. It does not change how the Hermes agent behaves. This page summarises what the fork adds.

    Runtime and CLI images

    Section titled “Runtime and CLI images”

    Two image variants are published to ghcr.io/forgeguard-ai/hermes-agent from one multi-target Dockerfile:

    • runtime-* — a full supervised server image. s6-overlay supervises the web dashboard and per-profile gateways; a boot reconciler restores gateways after a restart. Browser tools and messaging + Matrix adapters are baked in. Layout matches upstream’s Docker image (/opt/hermes install, /opt/data state volume).
    • cli-* — a lean interactive image for distrobox / one-off CLI use, with no dashboard/gateway stack and no supervisor. Distrobox host-integration packages and a locale are pre-baked; messaging adapters lazy-install on first use.

    Both carry the OCI labels com.forgeguard.hermes.prebaked=1 and com.forgeguard.hermes.variant=<runtime|cli>. See Runtime images and Distrobox / CLI image.

    Desktop installers

    Section titled “Desktop installers”

    Prebuilt Hermes Desktop installers are attached to each fork release:

    • Linux: .AppImage, .deb, .rpm (unsigned).
    • macOS: .dmg, .zip (ad-hoc signed, not notarized — no Apple Developer credentials on this fork).
    • Windows: not currently built.

    See Desktop artifacts.

    Release and version scheme

    Section titled “Release and version scheme”

    Releases are tagged with the Hermes Agent product version they ship (from pyproject.toml), e.g. v0.19.0. A re-cut of an already-released product version — such as a fork-only fix before the next upstream sync — adds a -forgeguard.<n> suffix (v0.19.0-forgeguard.2, counting the plain tag as cut 1). The upstream release the fork’s main is synced to (recorded in the FORK_UPSTREAM_BASE marker) appears in each release’s notes for traceability. Releases up to v2026.7.1-forgeguard.3 used older date-shaped <upstream-base>-forgeguard.<n> tags. Image -<version> tags are immutable; -latest tags roll. See Releases and upgrades and Image tag families.

    Fork CI and workflow guards

    Section titled “Fork CI and workflow guards”

    The fork adds release automation (a release-on-merge orchestrator that calls reusable image and desktop build workflows) and guards that prevent upstream-only publishing, deploy, and scheduled workflows from running on the fork. These are maintainer-facing and are documented under docs/maintainers/; they are not needed to consume the artifacts.

    ForgeGuard-only container behaviour

    Section titled “ForgeGuard-only container behaviour”

    Beyond upstream’s Docker image, the ForgeGuard images add: the multi-target Dockerfile split (runtime vs CLI), the com.forgeguard.hermes.* labels, pre-baked distrobox host-integration in the CLI image, and the HERMES_UID/HERMES_GID (with PUID/PGID alias) volume-ownership remapping. Dashboard authentication, persistence, ports, and health semantics otherwise follow upstream.

    Desktop app behaviour

    Section titled “Desktop app behaviour”

    The fork’s desktop builds default to Client Mode: the first-run chooser preselects connecting to an already-running Hermes backend (self-hosted container, VPS, home server), with a local backend as the secondary choice. The connection dialog supports an opt-in TLS bypass for self-signed certificates and remembers recent endpoints. See the upstream desktop guide for the shared product behaviour.

    Some earlier fork-only desktop features have since been absorbed by upstream and are no longer fork deltas: the Settings → Appearance Text Size control shipped in fork releases on the v2026.7.1 base was superseded in upstream v2026.7.20 by the equivalent UI Scale setting (same persisted zoom, plus Ctrl/Cmd+wheel zoom and half-step keyboard shortcuts), which the fork now uses unchanged.

    Supported platforms and signing state

    Section titled “Supported platforms and signing state”
    • Images: linux/amd64.
    • Desktop: Linux + macOS (ad-hoc signed, not notarized); Windows not built.

    See Platform compatibility for the full matrix and Compatibility for the version mapping.

    Section titled “Related”