Skip to content
vavio

Hermes broke after an update. How do I update safely and roll back?

Before updating Hermes, save its data, record the working version and use the updater for your installation. If an update breaks it, returning to older code may also require older data and matching dependencies. Neither hermes update nor /rollback provides a universal undo for every release change.

This guide checks Hermes v0.23.0 and v0.23.1 source and official documentation on 11 November 2026. We did not execute these update or recovery procedures for this article. The terminal examples are for an owner-operated source installation; a hosted service may manage code through a different path.

Choose the updater for your installation

Your installation Update through
Official source checkout hermes update
Docker Pull the selected image and recreate the container with its existing data mount
Microsoft Store, Windows MSIX or bundled macOS app The Store or that application’s Update control
Nix or Termux package Its package manager

The official update guide separates these paths. An image or package is not updated by rewriting its files with the source updater. Returning to an older Docker image also leaves the question of whether that image can read the current data.

Save data and record what worked

For a source install, record its Git commit, selected channel, active profiles and a small task that currently succeeds. Read the release notes for the version you intend to install. For example, the v0.23.1 notes describe a plugin-catalog size fix: older clients could fall back to their bundled catalog and miss new plugins or current pins. A release can change the tools you see as well as the application code.

Take a full data archive before the change:

hermes backup

The pinned backup documentation says this writes ~/hermes-backup-<timestamp>.zip. It covers profiles, configuration, credentials, memories, skills and sessions. Keep a protected copy away from the machine being changed: this archive contains secrets.

It excludes the application checkout, dependency environments, downloaded runtimes/models, caches and browser profiles. It is a data archive, not a machine image. Check the skipped-file report; a ZIP can exist with missing files. Save source edits separately. hermes backup --quick is a smaller state snapshot, not the same archive.

Use stable releases deliberately

For an official source checkout, stable follows the latest published final release rather than every change on main. To select it and then update:

hermes update --set-channel stable
hermes update --check
hermes update --backup

In the checked v0.23.0/v0.23.1 channel handler, the first command saves the per-install choice and exits. The later update performs the change. --backup requests the full pre-update archive; read its outcome rather than assuming it succeeded. Stable follows future releases when you update again; it is not a permanent pin to today’s version. Forks and mirrors can follow different defaults.

After updating, read the receipt and any restart warnings, check the active gateway and repeat your small task. An updater reporting success does not establish that your particular integration, model or scheduled job still works.

Check edited bundled skills

Bundled skills have their own update behavior. The pinned sync code updates pristine copies when their bundled version changes, but skips copies whose contents differ from the recorded origin hash. Your customization can survive while missing an upstream fix.

Inspect those differences:

hermes skills list-modified
hermes skills diff <name>

Save your changes before choosing a reset. hermes skills reset <name> clears its sync-tracking entry while keeping local files; adding --restore replaces the local copy with the bundled version. Read the bundled-skill guide before replacing a skill you rely on.

Roll back code and state as separate steps

First preserve the current state too, so recovery does not erase your only copy of work created since the update. Then establish which earlier code, dependency environment and data archive belong together.

The source-maintenance instructions describe manual Git maintenance separately from the managed updater. With all affected gateways stopped and local work preserved, this command in a clean source checkout selects the earlier v0.23.0 code:

git -C <hermes-source-directory> checkout --detach v0.23.0

That is only code selection, not a complete rollback or a permanent update-policy pin. Stop the affected gateways before changing their running code or restoring data, and follow the selected release’s dependency/bootstrap procedure. Do not assume the newer environment fits older code. There is no hermes update --version v0.23.0 option in the checked releases.

Upstream’s older-release recovery procedure calls for stopping the gateway, selecting older code and restoring a pre-update state snapshot or full backup with hermes import <backup.zip>. The documented downgrade guard covers stores with newer gateway-runtime history; it does not certify every release pair as compatible. Restore each affected profile. Messages and sessions created after the saved copy are absent from it, and quick snapshots skip individual files larger than 1 GiB.

Hermes can automatically return to pre-update code for certain post-pull syntax failures. That is narrower than recovering from every model, dependency or behavior regression. Likewise, /rollback restores checkpointed project changes; it is not the Hermes release updater.

If you use Vavio

Vavio sets up Hermes and looks after its server. Its current FAQ does not include backups or an uptime/recovery-time promise. This source-install guide does not establish an owner-accessible backup, import or version-switching path on Vavio, and it does not promise automatic Hermes version updates.

If your hosted Hermes regresses, contact support with the failing task and when it last worked. If you are deciding who should operate the machine, compare VPS and managed hosting against the current offer.

Sources

Written by Vavio with AI assistance and checked against pinned Hermes v0.23.0 and v0.23.1 source, official documentation and release notes. These update and restore procedures were not executed for this article.

More from the Vavio blog: Hermes Agent guides