Files
agent-estate-wiki/runbooks/update-hermes-safely.md
T

5.3 KiB

title, type, status, created, updated, verified_on, last_tested, confidence, tags, sources
title type status created updated verified_on last_tested confidence tags sources
Update Hermes safely runbook active 2026-07-22 2026-11-18 2026-11-18 2026-10-26 high
runbook
hermes
update
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/<install>/environments/<hash>/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

hermes backup --quick --label pre-update-$(date +%Y%m%d)

If you need a full backup instead:

hermes backup --label pre-update-$(date +%Y%m%d)

2. Check whether an update is available

hermes update --check

3. Review configuration version and backups

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

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):

~/.hermes/scripts/hermes-runtime-deps-guard.sh

5. Verify the new version

hermes version

6. Restart the required Hermes pieces

hermes gateway status
hermes dashboard status
hermes gateway restart
hermes dashboard restart

7. Sanity check health

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:
ls -lt ~/.hermes/config.yaml.bak*
cp ~/.hermes/config.yaml.bak.<timestamp> ~/.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:

ssh root@100.96.100.82
pct exec 450 -- <command>            # 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