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