v1.3.1 - API credential and gateway lifecycle hardening

Highlights

• Validate OpenAI-compatible API credentials before nginx or Hermes starts, without exposing rejected values.
• Keep add-on-managed API, profile, multiplexing, and foreground-supervision settings authoritative across shared, profile, external-secret, and managed configuration sources.
• Pin every gateway slot to its assigned Hermes profile so persisted interactive profile state cannot redirect or duplicate gateways.
• Run each profile gateway under a dedicated Linux subreaper/process-group supervisor with a fail-fast durable FIFO logger, bounded cleanup, orphan reaping, readiness signaling, and overlap prevention.
• Reject malformed environment records and unknown per-profile targets.
• Correct API documentation: /v1/health is public liveness; /v1/models verifies Bearer authentication.

Verification

• 108 unit tests passed; 2 expected platform-specific tests skipped.
• Shell syntax, Python syntax, YAML parsing, public-repository hygiene, and git diff --check passed.
• A fresh isolated Home Assistant local DEV add-on was built from this exact candidate and tested on HAOS/Linux with Hermes Agent v0.20.0 (v2026.8.3).
• Weak credentials failed before service startup without leakage.
• Two profile gateways passed direct and nginx-routed health and authenticated API checks.
• Container restart reused the shared install marker, resisted a poisoned sticky profile, replaced every old host process, and restored both profile gateways.
• An isolated worker-slot termination produced the expected containment proof and restarted only that slot while the primary gateway remained healthy.
• The DEV add-on, configuration, source, credential, and containers were removed afterward; the original stopped production add-on remained unchanged.

See the changelog for the complete details.

v1.3.0 - Hermes Desktop remote backend

Added

• Add an opt-in Hermes Desktop remote backend on container port 9119 using the official hermes serve contract and the existing add-on access password.
• Keep the Desktop backend disabled and its port unmapped by default; Home Assistant's Network settings choose the external host port.
• Support the full remote Desktop backend surface, including profiles, sessions, HTTP APIs, cookie authentication, WebSocket tickets, PTY, and events.

Security

• Require a non-blank access_password whenever the Desktop backend is enabled and fail closed before starting services when the requirement is not met.
• Pass the plaintext password to the launcher through stdin only; it never appears in argv or exported environment, and only the derived hash reaches Hermes.
• Document that authenticated Desktop access provides full agent control and must stay on a trusted LAN, VPN, or Tailscale path rather than the public internet.

Verified

• 66 repository tests passed, with 1 expected skip because nginx is not installed in the local test environment.
• Shell syntax, Python AST, YAML parsing, public-repository hygiene, and git diff --check passed.
• The exact v1.3.0 candidate was freshly built and installed as an isolated Home Assistant add-on without changing the stopped production installation.
• The installed backend required authentication, rejected unauthenticated profile access and a wrong password, established a cookie session, and exposed the default and worker profiles.
• A single-use WebSocket ticket connected once and was rejected on reuse.
• The codesign-verified Hermes Desktop app connected through its real cookie-authenticated remote path and reached the expected provider onboarding for the credential-free test profile.
• The final Devin review on PR #30 completed on exact head 05b4ee7dc0887c992fbf46cf09d417e4e3c9ef09 with 0 bugs; all four analyses were independently verified and required no candidate changes.

Configuration

1. Set enable_desktop_backend: true in the add-on options.
2. Configure a non-blank access_password.
3. Map container port 9119/tcp to a free Home Assistant host port in the add-on Network settings.
4. Connect Hermes Desktop to http://<home-assistant-host>:<mapped-port> with username hermes and the configured access password.

Related

• Review: #30
• Issue: #17

v1.2.1 - Dashboard Chat WebSocket lifecycle fix

Fixed

• Keep Dashboard Chat WebSockets open behind Home Assistant Ingress by enabling ingress_stream and rewriting proxied dashboard API Origin headers to the dashboard backend host.
• Fix direct-port Dashboard Chat WebSocket authentication when browsers send Basic auth plus the SPA ?token= query parameter.

Verified

• git diff --check - OK.
• bash -n hermes_agent/nginx-render.sh hermes_agent/run.sh hermes_agent/profile-init.sh - OK.
• python3 -m py_compile hermes_agent/dashboard-patches.py tests/test_dashboard_ingress_patches.py tests/test_multi_profile.py - OK.
• YAML parse checks for repository.yaml, hermes_agent/build.yaml, hermes_agent/config.yaml, and hermes_agent/translations/en.yaml - OK.
• uv run --with pytest python -m pytest -q tests/test_dashboard_ingress_patches.py - 21 passed.
• uv run --with pytest python -m pytest -q - 53 passed, 1 skipped.
• Live Home Assistant local DEV add-on lifecycle smoke - /dashboard/api/pty streamed binary TUI frames, /dashboard/api/ws emitted gateway.ready, and /dashboard/api/events stayed open through both HA Ingress and direct HTTPS access.
• Devin Review on PR #24 completed successfully with 0 bugs.

Related

• PR: #24
• Issue: #22

Hermes Agent Home Assistant Add-on v1.2.0

Hermes Agent Home Assistant Add-on v1.2.0

This release makes multi-profile setups lighter, faster, and safer to upgrade.

Added

• Add profiles_base so bare multi-profile names can default to upstream-style .hermes/profiles/<name> storage.

Changed

• Use one shared Hermes Agent clone and virtualenv for all profiles instead of installing Hermes separately for every profile.
• Preserve existing flat profile directories such as /config/amy during upgrades when the new profiles_base target does not exist yet.

Fixed

• Fix the shared-install dashboard patch helper call so startup uses the shared SRC_DIR instead of removed per-profile variables.
• Correct Home Assistant option text and storage documentation for the shared install and profiles_base behavior.
• Fix a README formatting typo in the OpenAI-compatible API authentication example.

Verified

Validated with an isolated Home Assistant local DEV add-on before release:

• local unit suite: 53 tests OK, 1 skipped
• pytest suite: 52 passed, 1 skipped
• shell syntax checks for run.sh, profile-init.sh, and nginx-render.sh passed
• YAML parse checks passed
• live DEV add-on started with two profiles: primary .hermes and secondary amy
• nginx -t passed inside the running add-on container
• one shared Hermes clone/venv was reused across profiles
• restart reused the shared install marker
• primary and secondary Dashboard/Terminal/API routes returned HTTP 200
• Home Assistant Ingress Dashboard WebSockets for /api/pty, /api/ws, and /api/events returned HTTP/1.1 101 Switching Protocols for both primary and /profile/amy
• legacy flat profile directory preservation was tested and passed

Because this changes runtime installation behavior for multi-profile setups, this is published as v1.2.0 rather than a patch release.

v1.1.2 - dashboard WebSocket upgrade fix

Patch release for the dashboard Chat tab WebSocket failure reported in #22.

What changed:

• Preserve WebSocket upgrades through the add-on nginx /dashboard/api/ proxy used by the embedded Hermes dashboard Chat tab.
• Forward Upgrade and mapped Connection headers for /api/pty, /api/ws, and /api/events while keeping normal REST calls on the same path sane.
• Add regression coverage for primary and multi-profile dashboard API routes across Home Assistant Ingress, direct HTTP, and direct HTTPS render modes.
• Include the pending documentation/storage changelog notes in this release.

Verification:

• git diff --check - OK.
• python3 -m pytest -q tests/test_dashboard_ingress_patches.py - 18 passed.
• python3 -m pytest -q - 43 passed, 1 skipped.
• bash -n hermes_agent/nginx-render.sh hermes_agent/run.sh hermes_agent/profile-init.sh - OK.
• python3 -m py_compile hermes_agent/dashboard-patches.py tests/test_dashboard_ingress_patches.py tests/test_multi_profile.py - OK.
• Live Home Assistant local DEV add-on smoke - add-on started, nginx -t passed, dashboard returned HTTP 200 through HA Ingress, and /dashboard/api/pty, /dashboard/api/ws, and /dashboard/api/events all returned HTTP/1.1 101 Switching Protocols.

Thanks to @imcvampire for the report and browser Network evidence that exposed the broken Chat WebSocket path.

v1.1.1 - dashboard patch helper fix

Patch release for the dashboard startup regression reported in #14.

What changed:

• Executes the installed dashboard patch helper directly instead of invoking it through a non-guaranteed python alias.
• Relies on the helper's #!/usr/bin/env python3 shebang, matching the Python executable installed in the add-on image.
• Adds a regression assertion so the startup path does not reintroduce the bare python dependency.

Verification:

• python3 -m unittest discover -s tests -> 43 tests OK, 1 skipped
• python3 -m py_compile hermes_agent/dashboard-patches.py tests/test_dashboard_ingress_patches.py tests/test_multi_profile.py -> OK
• bash -n hermes_agent/run.sh hermes_agent/profile-init.sh hermes_agent/nginx-render.sh -> OK

v1.1.0 - multi-profile support

Ships multi-profile support and includes the v1.0.8 gateway foreground fix that was tagged but never published as a GitHub Release.

What changed:

• Adds multi-profile mode via profiles, with the first profile keeping the existing root URLs and additional profiles exposed under /profile/<name>/....
• Adds flat Home Assistant-compatible profile_env_vars for per-profile .env overrides.
• Renders nginx routing per profile for dashboard, terminal, and API access.
• Adds profile initialization support and per-profile tmux/session naming.
• Keeps Hermes Gateway in the foreground under Home Assistant s6 so Supervisor tracks the add-on lifecycle correctly.
• Updates README, translations, and regression tests.

Verification:

• python3 -m unittest discover -s tests -q -> 43 tests OK, 1 skipped
• git diff --check -> OK
• python3 -m py_compile hermes_agent/dashboard-patches.py tests/test_dashboard_ingress_patches.py tests/test_multi_profile.py -> OK
• bash -n hermes_agent/run.sh hermes_agent/nginx-render.sh hermes_agent/profile-init.sh -> OK

Thanks to @imcvampire for the multi-profile work.

v1.0.7 - dashboard HA Ingress hardening

Fixes dashboard asset loading behind Home Assistant Ingress for modern Hermes dashboard builds.

Root cause:

• v1.0.6 fixed the nginx reload/startup failure from v1.0.5, but issue #6 exposed a different path-prefix failure.
• Modern upstream Hermes dashboards can rely on X-Forwarded-Prefix to derive HERMES_BASE_PATH and rewrite absolute Vite assets.
• Home Assistant Ingress prefixes include a random token, e.g. /api/hassio_ingress/<token>/dashboard, which can exceed upstream Hermes' current prefix sanity limit.
• When upstream dropped that long prefix, the dashboard HTML still loaded, but JS/CSS assets were requested from the wrong path and returned 404.

What changed:

• Adds an add-on-controlled import.meta.url fallback for modern dashboard HERMES_BASE_PATH so API, plugin, router, and asset paths keep working even if upstream prefix handling rejects HA Ingress' long path.
• Forces Vite to emit relative dashboard asset URLs with base: "./" for both modern and legacy dashboard sources.
• Rebuilds stale dashboard bundles when index.html still contains absolute /assets/... JS/CSS references.
• Keeps previous legacy dashboard compatibility patches and partial-patch repair behavior.
• Updates the landing page so /v1/health is shown as optional API server health, not Gateway health.
• Avoids polling /v1/health when the API server is disabled, preventing misleading nginx connect() failed log noise.
• Bumps the add-on version to v1.0.7.

Verification:

• python3 -m pytest -q → 13 passed
• git diff --check → OK
• python3 -m py_compile hermes_agent/dashboard-patches.py → OK
• bash -n hermes_agent/run.sh → OK
• Independent code review: PASS, no blocking findings

Thanks to @imcvampire for the full log and browser Network screenshot that made the remaining asset-path failure visible.

v1.0.6 - nginx reload fix for direct ports

Fixes the Home Assistant add-on startup failure introduced in v1.0.5 when direct HTTP/HTTPS ports are enabled.

Root cause:

• v1.0.5 placed map_hash_bucket_size 128; in the optional direct-ports nginx include.
• nginx had already parsed other map blocks by then, so reloading the final config failed with: "map_hash_bucket_size" directive is duplicate.
• The add-on exited after starting the gateway/dashboard, leaving the dashboard inaccessible.

What changed:

• Moves map_hash_bucket_size 128; into the main nginx template before the first map block.
• Removes the late duplicate directive from the direct-ports include.
• Adds a regression test that locks the directive ordering.
• Bumps the add-on to v1.0.6.

Verified on a real Home Assistant add-on installation:

• Fresh /config runtime after moving the previous add-on config aside.
• Upgrade/start path reaches nginx reloaded and All services started.
• Ingress landing page, dashboard, dashboard deep links, dashboard assets, dashboard API, and /v1/health all return 200.

Thanks to @imcvampire for reporting the post-v1.0.5 dashboard startup problem.

v1.0.5 - dashboard upstream compatibility fix

Fixes Home Assistant add-on startup failures caused by fragile dashboard source patching after upstream Hermes dashboard changes.

What changed:

• Moves dashboard source rewriting into a tested helper script instead of multi-expression sed calls.
• Skips source patches for modern Hermes dashboards that already support proxy prefixes via X-Forwarded-Prefix.
• Repairs partially patched v1.0.4 dashboard sources from failed previous starts.
• Keeps legacy fallback patches for older root-path-only Hermes dashboard sources.
• Forwards the dashboard prefix from HA Ingress or custom reverse proxies to Hermes.
• Adds regression tests for modern upstream, legacy fallback, and the sed delimiter failure class.

Thanks to @imcvampire for pinpointing the sed delimiter crash in PR #4.