--- title: Update Hermes safely type: runbook status: active created: 2026-07-22 updated: 2026-11-18 verified_on: 2026-11-18 last_tested: 2026-10-26 confidence: high tags: [runbook, hermes, update] sources: [raw/configs/hermes-config-sanitized.txt] --- # Update Hermes safely ## Purpose Update Hermes to a newer release without losing configuration, skills, or sessions. ## Symptoms that match this runbook - User wants to move to a newer Hermes version - `hermes version` shows an older build than expected - Update-related errors after manual changes in the install directory ## Prerequisites - Hermes install method: git-based install at `/home/hermes/.hermes/hermes-agent` - Working Python virtualenv at `/home/hermes/.hermes/hermes-agent/venv` - **Managed runtimes live under `~/.hermes/installs//environments//venv`** — these are what the gateway actually imports from; a missing dep there breaks cron jobs with no obvious trace (see [[incidents/2026-09-28-hermes-managed-runtime-deps]]) - Available disk space in Hermes install and backup paths - No active Hermes chat/webui shell issues before starting > **Re-verified 2026-11-18:** prerequisites hold on CT460 — `hermes --version` → `v0.23.0` from the git install at `/home/hermes/.hermes/hermes-agent`, legacy `venv/` present, three managed runtime venvs present under `~/.hermes/installs/019d0d114d22b7e6/environments/*/venv`. (CT450 currently runs `v0.23.1` — see [[incidents/2026-10-03-ct450-hermes-update]].) ## Procedure ### 1. Create a backup first ```bash hermes backup --quick --label pre-update-$(date +%Y%m%d) ``` If you need a full backup instead: ```bash hermes backup --label pre-update-$(date +%Y%m%d) ``` ### 2. Check whether an update is available ```bash hermes update --check ``` ### 3. Review configuration version and backups ```bash python3 -c "import yaml; print(yaml.safe_load(open('/home/hermes/.hermes/config.yaml')).get('_config_version'))" ls -la ~/.hermes/config.yaml.bak* ``` ### 4. Run the update with noninteractive flags ```bash cd /home/hermes/.hermes/hermes-agent git status --short hermes update --yes ``` Use `--branch main` only when deliberately tracking a branch other than the configured channel. The **stable** channel is currently the default and offers **v0.22.5** (`hermes update --check`, verified 2026-10-26; local install is v0.22.3 / `5b147ab036d6`). `--force-venv` rebuilds the virtualenv — avoid unless the venv itself is broken. **After any update, re-assert the managed-runtime dependencies** (the updater can leave a runtime without `fastembed`/`dotenv`/`mnemosyne`): ```bash ~/.hermes/scripts/hermes-runtime-deps-guard.sh ``` ### 5. Verify the new version ```bash hermes version ``` ### 6. Restart the required Hermes pieces ```bash hermes gateway status hermes dashboard status hermes gateway restart hermes dashboard restart ``` ### 7. Sanity check health ```bash hermes gateway status curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8787/health ``` ## Verification - `hermes version` shows a newer version than before - `hermes gateway status` is active - WebUI `/health` returns `200` - Providers reachable with [[provider-health]] ## Rollback - Rollback Hermes config: ```bash ls -lt ~/.hermes/config.yaml.bak* cp ~/.hermes/config.yaml.bak. ~/.hermes/config.yaml hermes gateway restart hermes dashboard restart ``` - Rollback entire Hermes install requires git revert or reinstall from previous checkout - If update warns about config migration, revert the backup and re-run manually ## Notes - Hermes version on this install: **v0.22.3** (2026.9.24), local `5b147ab036d6`; install tree rebuilt 2026-10-21 22:47→22:57 AWST. Stable **v0.22.5** available as of 2026-10-26 - Install directory: `/home/hermes/.hermes/hermes-agent` - Update preserves venv by default unless `--force-venv` is used ## Second instance — CT450 (`hermesagent`), updated 2026-10-03 (v0.19.0 → v0.21.5) CT450 has **no SSH**. Reach it from the PVE host: ```bash ssh root@100.96.100.82 pct exec 450 -- # or: pct enter 450 pct exec 450 -- su - hermes -c "/home/hermes/.local/bin/hermes --version" ``` `pct exec 450 -- hermes ...` fails (`Failed to exec "hermes"`): the binary is not on `lxc-attach`'s PATH. Use the absolute path or `su - hermes -c` (the dash gives a login shell, which sets `~/.local/bin`). A `hermes` login shell also prints a `hermes-setup` banner before output. **Pre-flight before running the update** (each of these cost one failed run on 2026-10-03): 1. `clang` installed — source-compiled Python dependencies will not build without it (`pct exec 450 -- bash -lc "which clang"`). 2. No stale `.install.lock` / `.lazy-refresh-incomplete` in the Hermes home. 3. `~/.hermes/hermes-agent` owned by `hermes:hermes` (a root-owned tree from an earlier root-run update breaks the in-place build). 4. Host Caddy/`keyring` file permissions sane (`0600` keyring blocked a step mid-update). **After:** `pct exec 450 -- su - hermes -c "/home/hermes/.local/bin/hermes --version"`, confirm CT460 production is untouched (separate config/skills/cron/memory). Full record: [[incidents/2026-10-03-ct450-hermes-update]]. ## Last tested 2026-10-26 on debian 13, git-based Hermes install — `hermes update --check` (stable v0.22.5 available), `hermes backup --help` and `hermes update --help` flags confirmed ## Related - [[restart-hermes]] - [[backup-wiki]] - [[provider-health]]