Updating & uninstalling

Hermes ships fast, so I update it often. The whole flow is one command, and it is careful about not breaking a working install.

Update to the latest version

hermes update

This pulls the latest code from main, reinstalls dependencies, and prompts you to configure any new config options that were added since your last update.

What actually happens during an update:

1. A lightweight snapshot of runtime state (pairing data, etc.) is saved.
2. git pull on main plus submodules.
3. Post-pull syntax validation. If a critical startup file fails to parse, Hermes auto-rolls back with git reset --hard so your shell stays bootable.
4. Dependency install via uv pip install -e ".[all]".
5. Config migration: new options are detected and you are prompted to set them.
6. Running gateways are auto-restarted so the new code takes effect.

TIP

If you skipped the config prompt, run hermes config check to see missing options, then hermes config migrate to add them interactively.

Preview before pulling

hermes update --check

Fetches and compares against origin/main without modifying anything. Handy in scripts or a cron job that should only act when an update exists.

Useful flags

hermes update --branch release-candidate   # track a non-main branch
hermes update --backup                      # full pre-pull backup of ~/.hermes

--backup archives config, auth, sessions, and skills before pulling. Worth it for a production gateway. You can make it the default:

# ~/.hermes/config.yaml
updates:
  pre_update_backup: true

Update from a messaging platform

If you run the gateway, you can update from Telegram/Discord/Slack/WhatsApp by sending:

/update

The bot goes offline for a few seconds during the restart, then resumes.

Post-update sanity check

hermes doctor       # config, dependencies, service health
hermes version      # confirm the version bumped
hermes gateway status   # if you run the gateway

If git status --short shows an unexpectedly dirty tree after an update, stop and inspect before continuing.

Rolling back

If an update introduces a problem:

cd /path/to/hermes-agent
git log --oneline -10
git checkout <commit-or-tag>
uv pip install -e ".[all]"
hermes gateway restart   # if running

After a rollback, run hermes config check and remove any config keys the older version does not recognize.

Uninstalling

hermes uninstall

The uninstaller asks whether to keep ~/.hermes/ (config, memory, skills) for a future reinstall. If you run the gateway as a service, stop and disable it first:

hermes gateway stop
# Linux:  systemctl --user disable hermes-gateway
# macOS:  launchctl remove ai.hermes.gateway

Offline note

hermes update needs network access to GitHub and PyPI. On an air-gapped machine, do a manual git pull + uv pip install -e ".[all]" from a mirror, or update on a connected machine and sync the repo across.