Hermes Agent Install and Update Troubleshooting: macOS PATH, Docker, Gateway Restarts
Fix Hermes Agent install and update failures across macOS PATH, missing git/ssh, Docker terminal backends, stale gateways, WSL, and safe source updates.
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.