---
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]]