Hermes Agent
Hermes update command: how to update Hermes Agent
Updated 19 November 2026
Which update method you use depends on how Hermes Agent was installed. A normal source install uses the hermes update command, a Docker install needs a new image and a recreated container, and the desktop and package installs have their own updaters. This page covers each, what to do around an update, and what to try when one fails.
Facts come from the Updating & Uninstalling page, the Docker setup page and the CLI commands reference of the Hermes Agent 0.23.2 documentation, read on 19 November 2026. The newest release on that day was v0.23.2, published 16 November 2026.
What hermes update does
For a managed source checkout, the update is one command:
hermes updateA source checkout of the official repository follows the stable channel. That means the latest published vX.Y.Z GitHub release, never a draft, prerelease or canary tag. Updates move from one release to the next, not commit by commit. Forks and mirrors keep tracking their main branch.
For an install that is allowed to be updated this way, the docs list these phases in order:
- A pre-update snapshot of selected state files for each profile (see the backup section below).
- The code update itself. On Linux and macOS the updater normally pauses gateways running from this install before changing the checkout, then starts them again once dependencies are prepared. Gateways it cannot pause can remain running and be refreshed afterward.
- A syntax check of the startup files before and after the move. If the check fails after the pull, Hermes rolls the checkout back to the commit it ran before, so the command line stays usable.
- Dependency preparation from the new lock file.
- Config migration, which prompts you for new options added since your version.
- A rebuild of the Hermes Desktop app, if it was built from this checkout.
- A gateway restart. Service-managed gateways (systemd on Linux, launchd on macOS) restart through the service manager. Manual gateways are relaunched when Hermes can map their process to a profile.
- For installs with two or more profiles that each run their own gateway, a migration to a single shared gateway, unless something blocks it.
You can also update from a chat. Send /update in Telegram, Discord, Slack, WhatsApp or Teams. The docs say this pulls the latest code, updates dependencies and restarts running gateways, and that the bot goes offline briefly (typically 5 to 15 seconds) and then resumes.
To follow every commit on main instead of releases, or to go back, the docs give these:
hermes update --set-channel main
hermes update --set-channel stable
hermes update --channel mainThe first two save the choice for the install. The third applies to one run only and saves nothing.
Which update method fits your install
The docs give this list for choosing the method:
| Install type | How to update |
|---|---|
| Managed source checkout | hermes update, or the source-built desktop’s update handoff |
| Docker image | Pull the chosen image and recreate the container with the same data mount |
| macOS bundled app | The desktop Update control, through electron-updater |
| Windows sideload MSIX | The desktop Update control and Windows App Installer |
| Microsoft Store package | Microsoft Store updates |
| Termux APT | pkg update, then pkg upgrade hermes-agent |
| Nix | Update the flake or profile and rebuild |
For Nix, the docs show nix flake update hermes-agent or nix profile upgrade hermes-agent, and note that Nix is no longer an explicitly supported install path (best effort only). The docs also say hermes update does not rewrite package-owned application files, and that you should not run Git or pip inside a signed app or an immutable image. For the desktop app itself, see Hermes Agent desktop app.
Check your version and preview an update
To see which version you run:
hermes --versionThe docs suggest comparing it with the latest release on the GitHub releases page. Two preview commands help before you commit to an update:
hermes update --checkcompares the checkout with the target of its channel without applying code, installing dependencies or restarting gateways. The docs add that the comparison can fetch Git metadata, so it is not a promise of zero writes to disk.hermes update --planprints the install kind, the running Hermes services across profiles, their supervisors and running code versions, and how each will be restarted. It changes nothing and is meant for machines that run several profiles or services.
If you would rather not see update notices in the terminal, hermes config set updates.check false turns off the passive version checks. Explicit hermes update --check and hermes update still work.
Before and after an update
Before. By default the update takes a quick snapshot of state files (pairing data, cron jobs, config.yaml, .env and auth.json) for every profile. The docs say this snapshot is best effort: if it fails, the update prints a warning and carries on. For a profile you care about, ask for a full backup of the Hermes home:
hermes update --backupTo make that the default, set updates.pre_update_backup to full in config.yaml. The other values are quick (the default) and off; --no-backup skips backups for one run. Quick snapshots skip individual files larger than 1 GiB, so the docs say a large session database needs the full backup. Also commit or stash any edits you made to the Hermes source, because the update stashes uncommitted source changes before pulling.
During. On Linux and macOS bots whose gateways are paused are offline during the code update and dependency preparation. An update with nothing to apply stops nothing. The restart waits for the gateway to be idle, and live work is not interrupted on a timer. To stop waiting, finish or stop the work the updater lists, or start the update with hermes update --force, which stops every gateway at once and interrupts that work.
After. The docs recommend these checks for a source update:
git status --short, and stop to inspect if the tree is unexpectedly dirtyhermes doctor, which checks config, dependencies and service healthhermes --version, to confirm the version moved as expectedhermes gateway status, if you use the gatewayhermes pm status, to inspect dependency preparation and any failed steps
Gateways are normally restarted for you. If one is still on old code, the update prints the exact restart command and every later command warns until it is done; hermes gateway restart restarts a gateway without applying an update. Manually started hermes serve or hermes dashboard backends are left running, and their owner has to relaunch them. See Hermes Agent dashboard for that side. Each run also writes a receipt to ~/.hermes/logs/update_receipts/ that records the steps taken and skipped.
Updating a Docker install
The Docker page says the image is stateless and that all user data lives in the directory mounted at /opt/data. To upgrade, pull the new image and recreate the container. Your data directory is kept, and the container runs non-interactive config-schema migrations against the mounted config.yaml before the gateway starts, writing timestamped backups next to config.yaml and .env first when a migration is needed. Before reusing an existing database on a virtiofs/9p bind mount, such as Docker Desktop on macOS or Windows, check its journal mode. An existing WAL database needs every Hermes process using it stopped before the offline conversion in the Docker documentation, and database.journal_mode: delete set in config.yaml. Alternatively, move the data to a native Docker volume. Fresh databases on detected virtiofs/9p mounts use DELETE mode automatically. The docs’ upgrade example:
docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
--name hermes \
--restart unless-stopped \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent gateway runWith Docker Compose:
docker compose pull
docker compose up -d- Do not run hermes update inside the container. Published images carry a marker that makes
hermes updaterefuse cleanly with exit code 2 and print the pull command instead. The same applies tohermes update --checkand the dashboard’s Update button. - Image tags.
latestandstableare the image accepted by the stable release gate,mainis the development image, andX.Y.Zis a versioned stable image. The docs say to use a digest for an exact deployment pin. - Gateways after the recreate. The docs say an image upgrade leaves the recorded gateway state as running, so a gateway that was running starts again on the next boot. Only one you stopped yourself with
hermes gateway stopstays down. - Config migration. Set
HERMES_SKIP_CONFIG_MIGRATION=1only if you need to inspect or migrate the persisted config by hand before the new image rewrites it.
Setup, Compose files and volumes are covered on Hermes Agent in Docker.
Rolling back and pinning
The docs are cautious here. A code checkout alone is not a data rollback: newer releases can migrate configuration or databases in ways older code cannot read, so use a coherent backup from before the update if an older release needs the earlier data format, and keep a copy of the current data before you restore anything.
In particular, an older release cannot run on a state.db that the gateway runtime has written. hermes update refuses a target that predates that runtime while any profile holds such history, and it stops before touching the checkout. To go back anyway, the docs give three steps:
hermes gateway stop- Check out the older release.
- Restore the newest pre-update snapshot with
/snapshot restore <id>, or a full backup taken withhermes update --backupusinghermes import <backup.zip>.
Sessions and messages created after the update are not in that snapshot. For source installs, hermes update --set-channel stable saves the stable-channel choice, while hermes update --branch NAME selects a branch tip for one run. These select update targets rather than a fixed version for future updates. A Docker install can use a versioned X.Y.Z tag; use a digest for an exact deployment pin. Nix has its own rollback with nix profile rollback; package installs use their package manager’s rollback or reinstall procedure.
When an update fails
- Fetch fails with
not a git repository. The update stops with a message that the checkout’s git data is damaged. Run the installer again (curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashon Linux, macOS and WSL2). It moves the damaged checkout aside ashermes-agent.broken-<timestamp>and clones fresh. Config, sessions and other data live outside the checkout and are kept. A checkout in another directory needs--dir <path>passed again, as the error prints. - Fetch fails with
should_include_obj should only be called on existing objects. Git 2.53 and newer can crash while fetching into a partial clone when some pack files lack a.promisormarker.hermes updatenormally marks the packs and retries once. On an install whose updater predates that fix, rerun the installer, or create the markers by hand with Hermes closed. The docs give a shell loop for that; do not removeremote.origin.promisorto get past the crash. - Disk filling up from
.git. The docs describe a treeless checkout from installers of late September 2026 that kept downloading trees, with one report reaching 434 GB. The recovery is to quit Hermes Desktop, end leftovergit rev-list,git maintenanceorgit commit-graphprocesses, and, if the disk is completely full, delete abandonedtmp_pack_*files in the checkout’s.git/objects/packdirectory. Then runhermes update, which converts the checkout. - The terminal disconnects mid-update. The update ignores
SIGHUP, so closing an SSH session does not kill it, and all output is mirrored to~/.hermes/logs/update.log. Reconnect and read it withtail -f ~/.hermes/logs/update.log. You do not needscreenortmux. - The post-pull syntax check fails. Hermes resets the checkout to the commit it ran before. Re-run
hermes updateonce the upstream fix lands. - A gateway is still on old code. The update exits 0 but prints a warning with the exact restart command, and every CLI start warns until it is done. Run that command, or
hermes gateway restart. - Another launch is repairing an interrupted update. A launch that waits more than 10 seconds for another one exits with status 1 and asks you to launch again in a moment.
- Windows. A git error falls back to downloading the release ZIP only if git has not touched the checkout yet; otherwise the update reports the git error and exits 1, and you re-run it after fixing git. If the maintained updater script is missing, for example after antivirus quarantine, repair the installation and review the quarantine report; the docs say not to disable antivirus protection. Before retrying a failed update they suggest looking at
hermes update --plan, the update log andhermes pm status. - Old Python. Hermes runs only on Python 3.14. A source install whose environment predates the PM migration can still run
hermes updateonce more, which provisions Python 3.14. Installing withpip install .on Python 3.11 to 3.13 gives a package that does not import, and the docs list those methods as unsupported.
For the exit codes: 0 is success, 1 is a pull, install or post-install error, and 2 means unexpected working-tree changes block git pull. If you are removing Hermes rather than updating it, see uninstall Hermes Agent.
Updates on ReadyHermes
On ReadyHermes you do not run an update command. Updates to the agent and to the machine under it are included in the plan, as described on managed Hermes Agent hosting. Running hermes update yourself inside a ReadyHermes assistant, for example over SSH, is not supported and not tested.
ReadyHermes assistants can run a Hermes release that is behind the newest one. On 14 November 2026 they ran a release older than 0.23, because we test a release before rolling it out. We do not promise a version number or a date for a given release. Plans start at US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month, and there is a 1-hour free trial. If you want to choose your own release and update timing, self-hosting is the better fit; see self-hosting vs managed hosting.
Questions
What is the Hermes update command?
For a managed source install, run hermes update. It follows the install's update channel (the latest stable release for the official repository), updates dependencies, prompts for new config options and restarts running gateways. Add --check to preview without applying code.
How do I check which Hermes Agent version I have?
Run hermes --version, then compare it with the latest release on the Hermes Agent GitHub releases page. hermes update --check compares the checkout with its channel's target without applying code, installing dependencies or restarting gateways, but it can fetch Git metadata.
How do I update Hermes Agent in Docker?
Pull the new image and recreate the container with the same data mount, for example docker pull nousresearch/hermes-agent:latest, then remove and run the container again, or use docker compose pull followed by docker compose up -d. Your data stays in the directory mounted at /opt/data. Running hermes update inside the container is refused.
Should I back up before updating Hermes?
The update takes a quick snapshot of state files by default, and the docs call it best effort. For a profile you care about, run hermes update --backup for a full backup of the Hermes home, or set updates.pre_update_backup to full in config.yaml.
Do I need to update Hermes myself on ReadyHermes?
No. Updates to the agent and the machine under it are included, and you do not run an update command. ReadyHermes tests a release before rolling it out, so an assistant can run a release that is behind the newest one.