--- title: Update Hermes safely type: runbook status: active created: 2026-07-22 updated: 2026-10-04 verified_on: 2026-07-22 last_tested: 2026-07-22 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` - Available disk space in Hermes install and backup paths - No active Hermes chat/webui shell issues before starting ## 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 --branch main ``` ### 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.21.5+6169.gab86a20 (2026.9.24); install tree rebuilt 2026-10-03 10:11 AWST - 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-07-22 on debian 13, git-based Hermes install ## Related - [[restart-hermes]] - [[backup-wiki]] - [[provider-health]]