107 lines
2.7 KiB
Markdown
107 lines
2.7 KiB
Markdown
---
|
|
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]]
|