To make a hermes agent backup, run hermes backup, which saves a zip of your whole Hermes setup (config, credentials, memories, skills, sessions and profiles) to ~/hermes-backup-<timestamp>.zip, and restore it later with hermes import. That is the full-setup backup. Everything else on this page is about when to use it, what it leaves out, and how it differs from profile exports and update backups.
📺 Watch: Hermes Agent + Agent OS Q&A!
🔥 Get the Agent OS as a free bonus: AI Profit Boardroom members get the full Agent OS zip, prompt libraries, daily tutorials and weekly live coaching calls. → Get inside
Your Hermes agent gets more valuable every week. It builds memories, writes its own reusable skills and collects cron jobs. Losing that because of a bad update or a dead laptop would hurt. A two-minute backup stops that.
I run Hermes daily inside my own Agentic Operating System, with a separate profile per model, so I back up before every big change. If you want the full Hermes courses, the Agent OS zip and four coaching calls a week, join the AI Profit Boardroom ($69/mo).
How hermes backup works
Per the Hermes docs, hermes backup creates a zip archive of your Hermes configuration, skills, sessions and data. It excludes the hermes-agent codebase itself, because this is a user-data backup, not a repo snapshot.
The options are short:
- -o or --output sets the output path. Default is ~/hermes-backup-<timestamp>.zip.
- -q or --quick takes a quick snapshot of only critical state files: config.yaml, state.db, .env, auth and cron jobs. Much faster than a full backup.
- -l or --label labels a quick snapshot.
- -k or --keep deletes older hermes-backup zips in the output folder beyond the newest N after a full backup. Default 3, and 0 keeps everything. Custom-named zips are never touched.
Two details I like. First, the backup uses SQLite's backup API, so per the docs it works correctly even while Hermes is running. Second, the exit status is honest. It returns 0 only when every selected file landed in the archive. If some files could not be added, it keeps the zip but exits 1, so a cron job will not treat a partial archive as a success. Exit 2 means another backup was already running.
What a full backup leaves out
Per the docs, the full backup skips things that are regenerable or unsafe to archive:
- the source checkout, dependency environments and downloaded tools, models and runtimes (models/, runtimes/, node/)
- build caches, checkpoints, previous backups and quick snapshots
- browser profiles, including copies of real-browser credentials
- bytecode, SQLite sidecars, gateway.pid, cron.pid and .backup.lock
- Unix sockets, devices and symlinks
Durable media in the cache stays in, such as cache/images, cache/audio, cache/videos, cache/documents and cache/screenshots. And the exclusions do not remove .env or auth.json, so your credentials are in the archive. Treat the zip like a password file.
Step by step: make and restore a Hermes agent backup
- Run the backup. Type hermes backup for a full archive, or hermes backup -o ~/backups/hermes.zip to choose the location.
- Read the report. The docs say full backups report files that fail to copy, so an archive can exist with missing data. Review the skipped-file report.
- Store it safely. Copy the zip off the machine. It holds your API keys.
- Stop the gateway before restoring. The docs warn to stop the gateway before importing to avoid conflicts with running processes.
- Restore. Run hermes import ~/hermes-backup-<timestamp>.zip. Every file in the archive overwrites existing files in your Hermes home. --force only skips the confirmation prompt that fires when a Hermes installation already exists.
- Verify. Run hermes setup to check API keys and provider config are working.
hermes import is careful too. Per the docs, it checks every member of the archive before writing anything. If the zip is damaged, it stops and leaves your Hermes home untouched. If you import an older backup over newer work, it warns you that session data was replaced by older contents.
📺 Watch: Hermes3D Is INSANE: AI Agents Now Have a 3D Office
hermes backup vs hermes profile export
This is the bit people mix up. Both make an archive. Only one is a full backup.
| Feature | hermes backup | hermes profile export |
|---|---|---|
| Use case | Full machine migration | Porting or sharing one profile |
| Scope | Hermes data root, with exclusions | Single profile directory |
| Includes | All profiles, global config, API keys, sessions | SOUL.md, memories, sessions, skills |
| Credentials | Included (.env and auth.json) | Excluded, stripped for safe sharing |
| Format | .zip | .tar.gz |
| Restore with | hermes import | hermes profile import |
The docs say it plainly: a profile export excludes credentials by design, so an export alone is not a full backup. Use profile export when you want to hand one agent to someone or move a single profile. For example, hermes profile export work ./work-backup.tar.gz, then hermes profile import ./work-backup.tar.gz work on the other machine. You may need to update paths or re-authenticate with providers afterwards.
Since I run one profile per model, profile export is handy for cloning a single agent. But for safety, I always keep a full hermes backup too. If you want a hand designing your own setup, book a free AI strategy session.
📺 Watch: Hermes AI Agents Just Went Portable
Back up before you update or uninstall
Update backups
Hermes protects you during updates on its own. Per the docs, every hermes update takes a pre-update snapshot of state files for each profile (pairing data, cron jobs, config.yaml, .env and auth.json) into that profile's state-snapshots/ folder. Automatic quick snapshots skip files larger than 1 GiB.
The setting is updates.pre_update_backup in config.yaml, with three modes:
- quick saves the selected state files. This is the default.
- full adds a zip archive of HERMES_HOME with the backup exclusions. Large data folders can take several minutes.
- off disables pre-update backups. --no-backup does this for one run.
For one full backup on demand, run hermes update --backup. The docs suggest this for high-value profiles like production gateways and shared team installs. A backup_keep setting controls how many full pre-update zips are kept (5 in the documented example).
One honest note from the docs: the snapshot is best-effort. If it fails, the update prints a warning and carries on. So for anything you care about, take your own hermes backup first.
Before uninstalling
hermes uninstall has modes that remove data. The docs call these destructive and say to make a backup first. If you are moving to a new machine rather than leaving, run hermes backup before removing the installation and check its skipped-file report before you delete source data.
Moving Hermes to another machine
Update backups protect an in-place update. For new hardware, the docs say to use hermes backup plus hermes import instead. Here is their process:
- Install Hermes on the new machine with curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. My Hermes Agent installation guide for 2026 covers this in detail.
- On the old machine, run hermes backup.
- Copy the zip across, for example with scp.
- On the new machine, run hermes import on the zip.
- Run hermes setup to check API keys and providers.
The full backup is not an application or runtime image. PM downloads dependencies again on the new machine, and bytecode and SQLite sidecars regenerate locally. The docs also give a manual fallback: rsync your ~/.hermes/ folder across while excluding the hermes-agent code folder.
This is the exact flow when you move from a laptop to a server. If you are picking one, see my best Hermes VPS breakdown. And since memories are a big part of what you are protecting, read best Hermes Agent memory to see how that layer works.
Other backups inside Hermes
A few smaller safety nets from the docs are worth knowing:
- Session export: hermes sessions export backup.jsonl saves your conversations. Add --redact before sharing.
- Skill snapshots: hermes curator backup takes a manual snapshot of ~/.hermes/skills/.
- Config copies: Hermes keeps point-in-time copies of config.yaml in backups/config/, and serves the newest good copy if your config breaks.
For the bigger picture of how I organise agents, profiles and backups, see my Agent OS guide. For which models are worth putting in those profiles, check Goldie Bench. And for daily Hermes updates, join the AI Profit Boardroom.
FAQ
How do I back up Hermes Agent?
Run hermes backup. It saves a zip of your config, credentials, memories, skills, sessions and profiles to ~/hermes-backup-<timestamp>.zip. Restore it with hermes import.
Does hermes profile export include my API keys?
No. Per the Hermes docs, profile export strips credentials for safe sharing. hermes backup includes them (.env and auth.json).
Can I run a backup while Hermes is running?
Yes. The docs say hermes backup uses SQLite's backup API, so it produces a consistent snapshot even while Hermes is active. Stop the gateway before you import, though.
Is the automatic update snapshot enough?
Not for a migration. The default quick snapshot saves state files only and is best-effort. For a full copy, run hermes backup or hermes update --backup.
Want a second pair of eyes on your setup? Book a free AI strategy session. Then make your first hermes agent backup today.
