Know which update path you're on
How you update depends on how you installed. The hermes update command is for source checkouts made by the install script. Desktop packages update through the in-app Update control; Docker users pull a new image and recreate the container; Termux uses pkg upgrade hermes-agent; Nix uses its own flake commands. Image-managed Docker installs refuse hermes update outright (exit code 2). If you're not sure which you have, hermes doctor reports the update method that applies.
Preview before you pull
Two read-only commands let you look before you leap. hermes update --check tells you whether your checkout is behind without applying anything. hermes update --plan lists the services, supervisors and restart methods the update would touch, which is worth a glance if you run gateways for several profiles.
If you'd like belt and braces, hermes backup writes your whole Hermes home to a zip file, and hermes update --backup adds a full pre-pull backup to the run.
What happens during an update
- Pre-update snapshot:
config.yaml, .env,auth.json, pairing data and cron jobs are saved. Quick snapshots are the default; set updates.pre_update_backup to quick, full or off. - Code update: the checkout moves to the configured release tag or branch. On Linux and macOS, gateways are paused first.
- Syntax check with automatic rollback: if a critical file fails to parse, Hermes resets the checkout to the pre-pull commit.
- Dependencies are prepared and validated.
- Config migration: you're prompted for new options. You can rerun this later with
hermes config checkandhermes config migrate. - Gateways that were paused or service-managed are restarted (skip with --no-gateway-restart).
Stable versus main
Official checkouts follow the stable channel by default: the latest published vX.Y.Z release, never drafts or prereleases. hermes update --channel main tries main once without saving the choice; hermes update --set-channel main follows every commit; hermes update --set-channel stable takes you back to releases. For an agent that runs your bots or scheduled jobs, stable is the sensible default. If passive update notices bother you, hermes config set updates.check false turns them off without affecting manual checks.
If you've edited the source
Local edits to the checkout are stashed during updates. In non-interactive runs, updates.non_interactive_local_changes chooses stash (default) or discard. Find parked edits with git stash list and reapply them with git stash apply. If you made local commits on main, the update resets main to the upstream branch and saves your old HEAD under refs/hermes-update-backups/, so nothing is lost. After any update, git status --short shows whether anything was reapplied.
After the update, and rolling back
A quick post-update check from the docs: hermes doctor, hermes --version, hermes gateway status and hermes pm status. If a bot still behaves like the old version, run hermes gateway restart or rerun hermes update, which retries interrupted restarts. Updates ignore terminal disconnects and log to ~/.hermes/logs/update.log.
Rolling back takes more care than updating. Automatic rollback only covers the syntax-check failure; code rollback never restores data. Once a new gateway has written state.db, older releases refuse to run on it. To go back anyway, stop the gateway, check out the older release, then restore the newest pre-update snapshot or a full backup with hermes import <backup.zip>. Sessions created after the update won't be in that snapshot, which is one more reason to stay on stable and update deliberately rather than on autopilot.
Related guides
- Hermes Agent install or update failed
- Where Hermes Agent runs: host vs work environment
- Hermes Agent profiles: separate agents for separate jobs
Primary sources
Spotted something wrong or out of date? Tell us on X at @HermesWatcher (opens in a new tab) and we will fix it.
New Hermes Agent updates every day on X. Follow @HermesWatcher