How-To Guide
How to Update Hermes Agent
Step-by-step guide to update Hermes Agent safely: pull the latest version, run migrations, restart the gateway, and verify the upgrade on macOS or Linux.
Quick answer
When Hermes install or update fails, preserve ~/.hermes state first, verify which hermes binary and source checkout are active, rerun with a full PATH on macOS, fix Docker/WSL prerequisites separately from the gateway, then restart the long-running gateway only after hermes doctor and package metadata checks pass.
Hermes Agent releases frequent updates with new features, bug fixes, and security patches. The update process is a single command and preserves all your memory, skills, and configuration.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed
- ☑Internet connection
- ☑A backup of ~/.hermes/ recommended before major version updates
Steps
- 1
Check current version
hermes --version to see what you're running
- 2
Check for updates
hermes update --check to see if a new version is available
- 3
Run the update
hermes update — this downloads and installs the latest release
- 4
Review changelog
Check the release notes at github.com/NousResearch/hermes-agent/releases
- 5
Restart Hermes
hermes restart to apply the update
Pro Tips
- 💡Check 'hermes --version' and compare with the GitHub releases page before updating — read the changelog for breaking changes first
- 💡Back up your ~/.hermes/ directory before major version updates: 'cp -r ~/.hermes/ ~/hermes-backup-$(date +%F)/'
- 💡If running on a VPS with PM2, the update command automatically restarts Hermes — no manual restart needed
Troubleshooting
❌ Update fails with permission error
✅ Run with sudo if Hermes was installed system-wide, or check that your user owns the Hermes install directory: 'ls -la $(which hermes)'.
❌ Hermes doesn't work after update
✅ Check the changelog for breaking config changes. Run 'hermes config validate' to detect outdated or invalid config keys.
❌ 'hermes update' says already up to date but GitHub shows a newer version
✅ Clear the update cache: 'hermes update --force'. The check cache can lag a few hours after a new release is published.
FAQ
Does updating Hermes erase my memory and config?
No. The update preserves memory, skills, and configuration under ~/.hermes. Back that directory up first anyway, then update and restart.
Why does `hermes` still show the old version after updating on macOS?
Usually a stale PATH. Reload your shell PATH (or open a new terminal) and run `hermes --version` again. If you installed via Docker, update the image and recreate the container while preserving the Hermes home volume.
Do I need to re-run gateway setup after an update?
Not normally, but restart the gateway so it picks up the new build. If channels misbehave after an update, version mismatch between client and gateway is a common cause.