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

127 lines
4.0 KiB
Markdown

---
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.<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:
```bash
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
## Related
- [[restart-hermes]]
- [[backup-wiki]]
- [[provider-health]]