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 |
|
|
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 versionshows 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.0from the git install at/home/hermes/.hermes/hermes-agent, legacyvenv/present, three managed runtime venvs present under~/.hermes/installs/019d0d114d22b7e6/environments/*/venv. (CT450 currently runsv0.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 versionshows a newer version than beforehermes gateway statusis active- WebUI
/healthreturns200 - 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-venvis 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):
clanginstalled — source-compiled Python dependencies will not build without it (pct exec 450 -- bash -lc "which clang").- No stale
.install.lock/.lazy-refresh-incompletein the Hermes home. ~/.hermes/hermes-agentowned byhermes:hermes(a root-owned tree from an earlier root-run update breaks the in-place build).- Host Caddy/
keyringfile permissions sane (0600keyring 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