snapshot: preserve central wiki state 2026-08-15 (7 modified + 1 new file)

2026-08-15 22:11:30 +08:00
commit 92e8028bb8
71 changed files with 9897 additions and 0 deletions
@@ -0,0 +1,106 @@
+---
+title: Update Hermes safely
+type: runbook
+status: active
+created: 2026-07-22
+updated: 2026-07-22
+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.19.0 (2026.7.20)
+- Install directory: `/home/hermes/.hermes/hermes-agent`
+- Update preserves venv by default unless `--force-venv` is used
+
+## Last tested
+2026-07-22 on debian 13, git-based Hermes install
+
+## Related
+- [[restart-hermes]]
+- [[backup-wiki]]
+- [[provider-health]]