How to update and uninstall Hermes Agent

If you already run Hermes Agent, skip the homemade git-and-uv checklist. Official docs give one command to upgrade and one command to remove the install. hermes update does not delete ~/.hermes, and hermes uninstall gives the option to keep it.

Preview before you pull

Compare your checkout with origin/main without modifying files or restarting a gateway:

hermes update --check

On a host that runs several profiles or services, hermes update --plan prints the full plan without changing anything: the install kind (git checkout, Docker image, Nix/apt managed), every running Hermes service with its supervisor and the code version it is serving, and the restart mechanism each one will get. Manually launched hermes serve / hermes dashboard backends appear too, from the spawn ledger. Image- or package-managed installs are told they are not updatable in place and given the right command instead. Every real update writes a receipt under ~/.hermes/logs/update_receipts/ (last 20 kept; latest.json points at the most recent). After restart, the updater compares each live gateway to the checkout and exits non-zero if any profile is still on pre-update code.

By default hermes update tracks origin/main. Pass --branch for a QA or release-candidate channel:

hermes update --branch release-candidate

hermes update --check --branch experimental   # preview behindness only

If HEAD is on a different branch, Hermes auto-stashes uncommitted work, switches to the target, and pulls. Missing remote branches fail cleanly and restore the stash.

Pinned or noninteractive installs can disable passive CLI version and banner checks:

hermes config set updates.check false

The default is true. Explicit hermes update --check and hermes update still work. This setting does not control the Desktop application's updater.

What `hermes update` does

hermes update

This pulls the latest code from main, updates dependencies, and prompts you to configure any new options added since your last update. If you skipped that prompt, run hermes config check, then hermes config migrate.

The run proceeds in this order:

Pre-update snapshot. A lightweight snapshot is saved by default (pairing data, cron jobs, config.yaml, .env, auth.json, and other runtime state; files over 1 GiB are skipped). Every profile gets its own copy under state-snapshots/. updates.pre_update_backup is quick by default, full for a zip of all of HERMES_HOME, or off to disable. Quick snapshots recover lost files; they are not code-rollback insurance. For a full HERMES_HOME zip before the pull:

hermes update --backup

--no-backup turns backup off for one run.

Git pull from main, including submodules.
Post-pull syntax validation and auto-rollback. Hermes compiles the nine critical files every hermes invocation imports at startup. If any fails to parse, it runs git reset --hard <pre-pull-sha> so the shell stays bootable. Re-run hermes update once the upstream fix lands.
Dependency install with uv pip install -e ".[all]".
Config migration for options added since your version.
Desktop rebuild (stage-and-swap). If Hermes Desktop was built from this checkout, the rebuild packs into a staging directory next to apps/desktop/release/, verifies, then renames over the previous build. Failure leaves the old app launchable; hermes desktop retries the rebuild.
Gateway auto-restart. systemd (Linux) and launchd (macOS) gateways restart through the service manager. Manual gateways relaunch when the PID maps to a profile. hermes serve / hermes dashboard backends record their bind address, stop before the code swap, and relaunch on the same host and port. Backends owned by a running Desktop app are left to the app's own respawn.
Multiplex migration. After the fleet is verified, a multi-profile install still running one gateway per profile is folded into a single multiplexed default gateway when nothing blocks it (same as hermes gateway migrate --multiplex --yes). Blockers are printed and nothing changes. Single-profile installs are never touched.

The restart is drain-first: new turns are refused, then in-flight work finishes, capped by agent.restart_after_turn_timeout (30 minutes by default). The updater prints remaining wait every 30 seconds. hermes gateway status lists the same units. Set the timeout to 0 to force the drain immediately.

hermes update ignores SIGHUP; output is mirrored to ~/.hermes/logs/update.log. SIGINT and SIGTERM still cancel. If an earlier update pulled code but did not finish restarting, the next hermes update retries even when the checkout is already current.

Docker images with the image-provenance marker refuse in-place update (exit code 2) and print docker pull nousresearch/hermes-agent:latest. Nix- and apt-managed installs refuse through the same gate.

On Windows, another hermes.exe holding the venv entry point open causes a refuse. Close Hermes Desktop, exit open REPLs, and run hermes gateway stop before retrying. --force skips that check.

If updater files are missing after antivirus quarantine, repair the install and review the quarantine report before retrying; do not disable antivirus protection.

After the update

git status --short — inspect unexpected dirty files before continuing.
hermes doctor
hermes --version
If you use the gateway: hermes gateway status

From Telegram, Discord, Slack, WhatsApp, or Teams you can send /update. The bot goes offline during restart (typically 5–15 seconds) and then resumes.

To roll back a bad update:

cd /path/to/hermes-agent

# List recent versions

git log --oneline -10

# Roll back to a specific commit

git checkout <commit-hash>

uv pip install -e ".[all]"

# Restart the gateway if running

hermes gateway restart

Then run hermes config check and remove unrecognized options from config.yaml if you hit errors.

Uninstall

hermes uninstall

The uninstaller gives you the option to keep ~/.hermes/ for a future reinstall. If you are moving machines rather than leaving, capture the home directory first with hermes backup.

If the gateway is a system service, stop and disable it before a manual removal:

hermes gateway stop

# Linux: systemctl --user disable hermes-gateway

# macOS: launchctl remove ai.hermes.gateway

rm -f ~/.local/bin/hermes

rm -rf /path/to/hermes-agent

rm -rf ~/.hermes            # Optional — keep if you plan to reinstall

Keep the last line optional. Do not delete ~/.hermes unless you want a clean wipe.

Run hermes update --plan on the live host, then hermes update --check. When the plan looks right, run hermes update. For snapshot modes, parked-branch behavior, and Windows locks, continue with the official Updating page.