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

4.0 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-10-04 2026-07-22 2026-07-22 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
  • Available disk space in Hermes install and backup paths
  • No active Hermes chat/webui shell issues before starting

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 --branch main

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

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-07-22 on debian 13, git-based Hermes install