How to Update Hermes Agent Safely

Steps

1. 1

   Read the v0.20 release notes before updating

   The Hermes Agent v0.20 Herald Release adds conversational voice, A2A, signed outbound webhooks, Desktop artifacts, grounded citations, and new CLI commands. Review the focused release guide before changing a production profile.

2. 2

   Identify the install and check the current version

   Run which hermes, hermes --version, and hermes doctor. Hermes detects git-installer, Docker, and NixOS layouts differently, so confirm the active binary before changing anything.

3. 3

   Preview the update without modifying files

   Run hermes update --check. It fetches and compares your checkout with origin/main without pulling code, installing dependencies, or restarting gateways. Read the latest release notes before a production update.

4. 4

   Take the right pre-update backup

   Normal updates take a lightweight state snapshot. Use hermes update --backup for a full HERMES_HOME archive on production gateways or important profiles. Commit intentional source changes first; Hermes auto-stashes a dirty source checkout, but restoring custom edits can conflict with new code.

5. 5

   Close conflicting Windows or Desktop processes

   On Windows, close Hermes Desktop, exit open Hermes REPLs, and stop the gateway before updating so hermes.exe and venv files are not locked. For a Desktop retry loop, close every Hermes window before using the terminal updater and inspect ~/.hermes/logs/bootstrap-installer.log.

6. 6

   Run the update

   Run hermes update. It pulls the configured branch, validates critical Python files, refreshes Python and Node dependencies, migrates config, syncs bundled skills, and attempts to restart running gateway profiles. Use /update from a supported messaging platform only when you can tolerate the bot going briefly offline.

7. 7

   Read partial-update errors literally

   If Hermes says Node dependencies did not refresh, the code and Python environment may be current while Desktop, dashboard, or TUI assets remain mixed. Run node --version and npm --version, then compare the error's Required and Actual engine ranges with the current Hermes package.json; use a supported LTS Node/npm pair instead of bypassing engine-strict.

8. 8

   Migrate config only when prompted or reported

   Run hermes config check after the update. If it reports missing options, run hermes config migrate. Do not use obsolete commands such as hermes config validate.

9. 9

   Verify the updated runtime

   Run hermes --version, hermes doctor, and hermes gateway status. For a git install, inspect git -C ~/.hermes/hermes-agent status --short. If Hermes restored local source changes, review the diff before blaming the new release.

10. 10

    Prove one real workflow

    Open the private Hermes dashboard, confirm the intended profile/provider, then run one harmless tool call and one real Telegram, Discord, cron, or webhook test. A successful update message does not prove every long-running channel loaded the new code.

Pro Tips

• 💡Use hermes update --check before changing a production install and hermes update --backup when the profile is expensive to reconstruct.
• 💡The normal updater already attempts to restart running gateway profiles; use hermes gateway restart only when validation shows a gateway stayed stale.
• 💡Docker installs do not support hermes update; pull the new image, recreate the service, and preserve the Hermes home volume.
• 💡Do not solve Node/npm engine failures with random global upgrades. Read the current repo engine constraints and use a supported LTS combination.
• 💡If prompted to restore local changes, choose yes only for source edits you recognize. Choosing no leaves the update stash preserved for later review.
• 💡If an SSH terminal disconnects, inspect ~/.hermes/logs/update.log; current updates mirror progress there and ignore SIGHUP.

Troubleshooting

FAQ

Related setup and cost guides