Tutorial 4: Updating & Uninstalling Hermes | Easy Understand Hermes Agent

This is part of the Hermes Agent official tutorial series. View all tutorials

Updating Hermes is like getting a new version of your favorite phone app—except instead of tapping “Update” and hoping for the best, Hermes takes a safety photo of your current setup, downloads the new code, checks that nothing broke, and even asks you about any new settings—all in one go.

Step 1: Run the One-Command Update

Open your terminal and type:

hermes update

That’s it. Hermes will pull the latest code from the official main branch, install any new dependencies, and then prompt you to configure any brand-new options that were added since your last update.

Key point: You don’t need to manually download anything. This single command handles the whole process.

Step 2: Understand What Happens Behind the Scenes

Here’s the breakdown of what hermes update actually does, step by step:

Pre-update snapshot — Before touching anything, Hermes saves a lightweight backup of your important files (pairing data, scheduled jobs, your config.yaml, .env, and auth.json). Files larger than 1 GiB are skipped so a huge database never slows down the update. You can control this with the updates.pre_update_backup setting:
- quick (default) — saves the essentials
- full — zips your entire Hermes folder
- off — no backup at all
Git pull — Downloads the newest code and updates any submodules (smaller linked components).
Post-pull safety check — After pulling, Hermes compiles the nine critical files that every command loads at startup. If any file is broken (like a leftover merge-conflict marker or a truncated file), Hermes automatically rolls back to the previous version. Your shell stays usable, and you can retry the update later once the fix is available.
Dependency install — Runs uv pip install -e ".[all]" to make sure all new or changed libraries are in place.
Config migration — Hermes detects any new configuration options and asks you to set them right then.
Gateway auto-restart — If you have any running gateways (background processes that connect Hermes to chat apps), they get refreshed automatically so the new code takes effect immediately.

Step 3: Updating from a Different Branch (Advanced)

By default, hermes update tracks the main branch. But if you’re testing a release candidate or an experimental feature, you can specify a different branch:

hermes update --branch release-candidate
hermes update --check --branch experimental   # just check how far behind you are

If your local code is on a different branch, Hermes will stash any uncommitted work, switch to the target branch, and pull. Branches that don’t exist locally are created automatically from the remote. If the branch doesn’t exist anywhere, Hermes fails cleanly and restores your stashed changes—so you’re never left in a broken state.

Step 4: What About Local Changes?

Interactive updates (with a terminal): Hermes stashes your uncommitted changes, pulls the update, then asks whether you want to restore them. You stay in control.
Non-interactive updates (from the desktop app or a gateway trigger): There’s no one to ask. The updates.non_interactive_local_changes setting decides what happens to your local changes automatically.

Step 5: If You Skipped the Config Prompt

During an update, Hermes prompts you to configure new options. If you accidentally skipped that prompt, don’t worry. Run:

hermes config check

to see what’s missing, and then:

hermes config migrate

to interactively add them.

Summary

Updating Hermes is a safe, guided process: it backs up your state, pulls new code, validates everything, installs dependencies, migrates config, and restarts gateways—all with one command. The built-in rollback protects you from broken updates, and the branch option gives you flexibility for testing.

Next up: In Tutorial 5, we’ll cover Uninstalling Hermes completely—including how to remove all data, configs, and background services so your system is truly clean. Stay tuned!