Migrate Hermes Agent to a New Machine: Backup, Import, Done
To migrate Hermes Agent to a new machine, the docs give a simple answer: run hermes backup on the old computer and hermes import on the new one. That moves your config, credentials, memories, skills, sessions and profiles. Here’s the full step-by-step, what the backup leaves out, and the mistakes that cost people their setup.
Key takeaways
Full move: hermes backup on the old machine, hermes import <zip> on the new one.
A full backup includes credentials. A profile export strips them.
Don’t use --quick for a migration.
hermes migrate is for other agents, not machine moves.
The Hermes FAQ separates moving everything from moving one agent:
hermes backup
hermes profile export
File
.zip of the whole data root
.tar.gz of one profile
Credentials
Included (.env, auth.json)
Stripped
Use it for
Moving your whole setup to new hardware
Porting or sharing one agent
Restore with
hermes import <zip>
hermes profile import
1. Back up the old machine
hermes backup
# writes ~/hermes-backup-.zip
# use -o to save it somewhere else
The backup covers config, credentials, memories, skills, sessions and profiles. It uses SQLite’s backup API, so it’s safe to run while Hermes is running. Check the exit code before you go any further:
0: every file landed.
1: Backup incomplete. The zip is kept, but review the skipped-file report.
2: another backup was already running.
If your credential vault key is in keychain mode, the backup won’t carry it. Run hermes vault key migrate --to file first.
Want your AI agents moved and set up properly? Inside the AI Profit Boardroom you get the Agent OS — Hermes, OpenClaw, OpenCode, Claude and Codex in one place — plus step-by-step Hermes training and four live coaching calls a week.
Desktop packages for macOS and Windows are also on the install page. Then copy the zip across, for example with scp ~/hermes-backup-<timestamp>.zip newmachine:~/.
3. Import and check
Stop any running gateway first. The docs warn about this.
Run hermes import ~/hermes-backup-<timestamp>.zip. It overwrites existing files in the Hermes home. -f only skips the confirmation prompt.
Run hermes setup to check your API keys and providers work.
Import checks every file’s CRC before writing, so a damaged archive leaves your home untouched. If an older backup would replace newer sessions, it warns you with before and after counts.
4. After the move
Reinstall the gateway service if you use one, with hermes gateway install.
Re-pair messaging platforms that need it. WhatsApp uses QR pairing, so plan to run hermes whatsapp again.
You may need to update paths or sign in to providers again, as the FAQ notes.
Only remove the old install once everything works.
hermes backup isn’t a full disk image. Per the CLI reference, it skips the hermes-agent code, dependency environments, models/, runtimes/, node/, checkpoints, browser profiles, regenerable cache and old backups. It keeps cached images, audio, video, documents, screenshots and citations.
And hermes backup --quick only saves critical state. In the docs’ words, “it is not a replacement for the full backup before a machine migration.”
Moving just one agent
hermes profile export work ./work-backup.tar.gz
# on the new machine
hermes profile import ./work-backup.tar.gz work
Profile exports always leave out .env, auth.json, token files, the vault, browser profiles and platform sessions, so add your credentials again afterwards. They can include memories and sessions, so check with tar -tzf before giving one to someone. Import refuses to overwrite an existing profile. For sharing the same agent to many machines, the profile distributions docs cover hermes profile install.
Don’t confuse it with hermes migrate
hermes migrate sounds right but does something else. It imports from other agents like OpenClaw, Claude Code, Codex, Cursor and Grok Bot (import docs). It doesn’t move Hermes between machines. The manual fallback in the FAQ is rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/.
My verdict
Run a full hermes backup, check it exits 0, stop the gateway, import, then run hermes setup and re-pair WhatsApp. That’s the documented way to migrate Hermes Agent to a new machine without losing your memories, skills or keys.
About Julian Goldie
I’m Julian Goldie — founder of Goldie Agency and the AI Profit Boardroom. I test new AI agents almost every day for 432K+ YouTube subscribers and run Hermes, OpenClaw, OpenCode, Claude and Codex side by side in my own Agent OS. Claim your free strategy session or join the AI Profit Boardroom.
Last updated November 2026. This page is a living guide to migrate hermes agent to new machine — the facts here move fast and it is updated as they do.
