Hermes Agent Backup, Restore & Migration

Everything that makes your agent yours is in the Hermes data directory (HERMES_HOME). The program itself can be reinstalled.

Inside it: config.yaml, .env (API keys), auth.json (OAuth tokens), SOUL.md, memories/ (memory), skills/ (skills), state.db (every session), cron/, plugins/, and profiles/.

$hermes backup                                  # full: ~/hermes-backup-<timestamp>.zip
$hermes backup -o ~/Backups/hermes-$(date +%F).zip
$hermes backup --quick --label pre-upgrade      # quick state snapshot

• Safe while Hermes is running. Databases are copied with SQLite's backup API, so you don't need to stop the gateway to back up.
• Check the exit code. 0 means every file landed. 1 (“Backup incomplete”) keeps a partial zip and lists what was skipped — read it before deleting anything. 2 means another backup was running.
• Old zips are pruned. A full backup keeps the newest 3 hermes-backup-*.zip files in the output folder (--keep N; 0 keeps all). Pruning is skipped after an incomplete backup.
• Not included: the Hermes program, downloaded local models and runtimes, browser profiles (they hold real browser cookies and logins), regenerable caches, session checkpoints, earlier backups, and SQLite's -wal/-shm sidecars.
• A quick backup is not a migration backup. The official FAQ says so directly; use a full backup before moving machines.

To restore a quick snapshot, start hermes and use /snapshot (lists snapshots) and /snapshot restore <id>.

$hermes gateway stop                       # and quit the Desktop app / dashboard
$hermes import ~/hermes-backup-<timestamp>.zip
$hermes doctor
$hermes gateway start

• Import overwrites. Every file in the archive replaces the file of the same name in your data directory. If Hermes is already set up there, it asks first; --force skips the question.
• Damaged archives are refused before anything is written — every member is checksum-checked first.
• Partial restores are reported: exit code 1 and an “Import incomplete” summary if any file could not be restored.
• Older-over-newer is flagged. If the imported state.db has fewer messages than the one it replaces, the summary warns that anything after the backup date is gone from the restored copy.
• Databases are written into the existing file rather than swapped, so a process that still has it open sees the restored data. If that can't be done safely, the database is skipped with a warning — stop the process and rerun.

We checked the current docs for a warning to import only into a fresh, empty install. It is not there today: the documented requirement is to stop the gateway, and the confirmation prompt covers importing over an existing setup. Importing into a new install is still the cleanest case, because nothing is being overwritten.

$hermes profile export work -o work.tar.gz
$hermes profile import work.tar.gz --name work
$
$hermes sessions export all-sessions.jsonl
$hermes sessions export --format html --newer-than 1w --redact archive.html

• Profile exports strip API keys. Static keys have to be re-entered and OAuth logins signed in again on the destination (hermes -p <name> auth add <provider>). The same export is /export in chat and ⌘K → Export profile in Desktop.
• Machine-specific tools don't travel. installs/, tools/, and cache/ are left out; reinstall dependencies on the destination.
• Session exports are one-way. They produce readable or machine-readable archives; there is no documented command to import them back as live sessions. Use a full backup if you need sessions restored.
• --redact masks recognizable credential patterns only. Anything else sensitive you discussed stays in the export.

1. Install Hermes on the new machine (install guide). Don't start its gateway yet.
2. On the old machine: hermes backup, and confirm it exits 0.
3. Copy the zip over an encrypted channel, e.g. scp ~/hermes-backup-*.zip newhost:~/.
4. Stop the gateway on the old machine (hermes gateway stop, or disable its service). Two gateways using the same Telegram or Discord bot token conflict.
5. On the new machine: hermes import ~/hermes-backup-<timestamp>.zip, then hermes setup or hermes doctor to confirm providers work.
6. Start the gateway there (on a server, as a service — see the VPS guide) and run hermes cron doctor.

• Absolute paths don't move. A cron job's --workdir or a config path that doesn't exist on the new machine will fail; hermes cron doctor flags missing working directories.
• Local models aren't in the zip. Re-download them on the new machine.
• The official docs don't describe exporting from or importing into Hermes Cloud or third-party managed hosts. Ask the host before assuming your data can move — see hosting.

In Docker, the data directory is whatever is mounted at /opt/data. Back it up with Hermes inside the container rather than by copying files on the host, which on Docker Desktop can capture a database mid-write:

# Back up to a folder that lands on the host through the mount
$docker exec hermes hermes backup -o /opt/data/backups/hermes-$(date +%F).zip
$
# Restore: stop the container, then run import in a one-off container
$docker compose stop
$docker run --rm -it -v ~/.hermes:/opt/data -v ~/Backups:/restore \
$  nousresearch/hermes-agent import /restore/hermes-2026-09-26.zip
$docker compose up -d

Moving from a native install to Docker (or back) uses the same zip: the archive holds the data directory's contents, and the container treats /opt/data as that directory.

• A full backup is a credential file. It includes .env (provider API keys, bot tokens) and auth.json (OAuth tokens) for every profile. The official FAQ states both are included.
• Encrypt before it leaves the machine (for example with age or gpg), and never commit it to a Git repository, including private ones.
• Sessions and memory are personal data. state.db holds every conversation, including anything you pasted. A profile export has no keys but still carries memory and SOUL.md.
• If a backup leaks, rotate the keys and tokens it contained; deleting the file doesn't revoke them.
• Browser profiles are excluded from full backups on purpose, because they hold real browser cookies and saved logins.

Many people look up backups after sessions vanish or Hermes reports its database is locked or corrupt. Some context: v0.21.0 (August 31, 2026) rewrote how the session store handles connections, and for some installs it made state.db fragile. v0.21.2 (September 11), titled “The state.db Patch Release”, lists six fixes closing 44 issues; later releases continued the work. On Docker Desktop, see the bind-mount trap.

$hermes gateway stop          # stop EVERY Hermes process: gateway, Desktop, dashboard
$hermes doctor                # names any process still holding the database
$hermes sessions recover --source ~/.hermes/state.db --inspect-only   # read-only check

• Don't delete state.db-wal or state.db-shm. The write-ahead log can hold conversations not yet in state.db; deleting it is how a recoverable state becomes real data loss.
• Don't copy state.db on its own as a backup — the three files form one image. Use hermes backup.
• Don't run hermes doctor --fix while Hermes processes are running, and don't ask the agent to repair its own database.
• If recovery isn't possible, restore the newest snapshot from state-snapshots/ or your last full backup.