To migrate Hermes Agent to new machine hardware, run hermes backup on the old computer, copy the zip across, install Hermes on the new computer, run hermes import on that zip, then run hermes setup to check your API keys and providers. That is the route the Hermes docs give for moving a whole setup, and it is not the hermes migrate command.
📺 Watch: How to Run Hermes Agent OS on a VPS
🔥 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
This guide walks through each step, shows what moves and what stays behind, and covers the one-profile option for when you only want to move a single agent.
Julian Goldie shares the agent setups he runs in his own business inside the AI Profit Boardroom. If you want a second pair of eyes on a move to a VPS or a new laptop, book a free AI strategy session.
Why hermes migrate is the wrong command
The name trips people up. hermes migrate sounds like the move-machines command, but the CLI reference describes something else.
It imports from other agents: OpenClaw, Claude Code, Codex, Cursor, Grok Bot and OpenBot. It also rewrites config, for example migrate xai and migrate relay. Since v0.23.0 the importers live in the agent-importers plugin.
If you are coming from Grok Bot rather than from another Hermes install, that is a separate job, covered in the guide on how to migrate Grok Bot to Hermes.
For Hermes to Hermes, the updating page is clear: update backups protect an in-place update, and a move to different hardware uses hermes backup plus hermes import.
How to migrate Hermes Agent to new machine setups, step by step
These steps follow the Hermes FAQ section on exporting Hermes to another machine, plus the warnings in the CLI reference.
Step 1: check where your vault key lives
If you keep your credential vault key in the operating system keychain, a backup carries the vault without its key. The credential vault docs say to run hermes vault key migrate --to file before you move a profile to another machine.
Run hermes vault key first to see where the key sits now. If it is already a file, skip this step.
Step 2: take a full backup on the old machine
Run hermes backup. By default it writes a zip to your home folder named hermes-backup plus a timestamp. Add -o with a path to save it somewhere else.
You do not need to stop Hermes for this. The backup uses SQLite's backup API, so it is safe while Hermes is running.
Use the full backup, not --quick. The docs put it plainly: "It is not a replacement for the full backup before a machine migration."
Step 3: read the exit code
Exit code 0 means every file landed in the zip. Exit code 1 means the backup is incomplete: the zip is kept, but some files were skipped. Exit code 2 means another backup was already running.
On a 1, read the skipped-file report before you go any further.
Step 4: install Hermes on the new machine
The FAQ uses the install script: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash. The installation page also documents desktop packages for macOS and Windows.
Step 5: copy the zip across
The FAQ example is scp from the old machine to the new one. Any method that copies the file intact works, and the import checks the archive anyway.
Step 6: stop the gateway, then import
The CLI reference warns you to stop the gateway before importing. Then run hermes import followed by the path to your zip.
The import overwrites existing files in your Hermes home. If Hermes is already set up on that machine, it asks you to confirm. -f or --force only skips that prompt.
Step 7: run hermes setup
The last step in the FAQ is hermes setup on the new machine, to check that API keys and provider config work.
If you run Hermes as a background service, set it up again with hermes gateway install. If you use WhatsApp, plan to pair it again with hermes whatsapp.
📺 Watch: Hermes Agent: New Voice Activation Update is INSANE!
What moves and what stays behind
This is the table to check before you wipe the old machine.
| Item | Full hermes backup | hermes profile export |
|---|---|---|
| Config and skills | Included | Included for that profile |
| Memories and sessions | Included | Can be included |
| API keys (.env, auth.json) | Included | Stripped |
| All profiles | Included | One profile only |
| Hermes code and dependency environments | Excluded | Excluded |
| Models, runtimes, checkpoints | Excluded | Excluded |
| Browser profiles | Excluded | Excluded |
| Platform sessions and pairing stores | Not stated in the docs | Excluded |
| File format | .zip | .tar.gz |
From the cache folder, the backup keeps images, audio, videos, documents, screenshots and citations. Everything else in the cache is treated as regenerable.
The excluded items get rebuilt or downloaded again on the new machine. The docs note that runtime downloads are often tens of GB, which is why they stay out of the zip.
📺 Watch: NEW Hermes Agent Cloud Update is INSANE!
What the import does with your sessions
Before writing anything, hermes import checks the CRC of every file in the archive. A damaged zip leaves your Hermes home untouched and exits 1.
A partial restore also exits 1, with an "Import incomplete" summary. The files that landed stay in place.
Databases such as state.db, kanban.db and response_store.db are written into the existing database file instead of being swapped in. If an older backup replaces newer sessions, the import prints a warning with before and after session and message counts.
So if you see that warning on a fresh machine, check you copied the right zip.
Moving just one agent with a profile export
Sometimes you only want one agent on the new box, for example a support agent moving to a VPS while everything else stays on your laptop.
The FAQ route is hermes profile export work ./work-backup.tar.gz on the old machine, then hermes profile import ./work-backup.tar.gz work on the new one.
Three things to know:
- Profile exports always strip credentials, so you add your API keys again.
- Profile import refuses to overwrite an existing profile and cannot import as default.
- The FAQ says you may need to update paths or re-authenticate with providers.
In a chat session, /export does the same job, and the desktop app has Export profile and Import profile in its command menu. The profile distributions page covers the details.
If you want to see how a full Hermes setup runs day to day before you move it, the Agent OS guide walks through the whole system.
Checks after the move
Run these before you delete anything on the old machine:
- Confirm the backup exited 0, or that you read the skipped-file report.
- Confirm the import finished with no "Import incomplete" line.
- Run hermes setup and check every provider.
- Open a past session and check your memories and skills are there.
- Check your cron jobs are listed.
- Reinstall the gateway service if you use one, and re-pair WhatsApp or other messaging that needs it.
- If you used the keychain for your vault, check the vault opens.
The docs say to review the skipped-file report before removing the source install. Keep the old machine running until every check passes.
Moving machines is also a good moment to look at which model you run. The Goldie Bench leaderboard scores models on the same fixed tasks, and your provider keys come across in the full backup.
Inside the AI Profit Boardroom you get step-by-step video trainings and the installable Agent OS. For help planning your own move, book a free AI strategy session.
The manual fallback
The FAQ also gives an rsync fallback that copies the Hermes folder directly and leaves out the code repo: rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/.
The backup and import route gives you more checks: exit codes, the CRC test, the session warning and the skipped-file report. The rsync copy gives you none of those.
The same vault rule applies. A copied Hermes folder does not carry a keychain key either.
For more on how Hermes stores credentials, read the Hermes Vault guide before you move.
FAQ
How do I move Hermes Agent to a new computer?
Run hermes backup on the old machine, copy the zip, install Hermes on the new machine, run hermes import on the zip, then run hermes setup to check your providers.
Does hermes backup include my API keys?
Yes. A full backup includes .env and auth.json. A profile export strips them.
Can I back up Hermes while it is running?
Yes. The backup uses SQLite's backup API and is safe while Hermes runs. Stop the gateway before you run hermes import, though.
Will my WhatsApp bot keep working after the move?
The docs do not promise that. Profile exports exclude platform sessions, and WhatsApp pairing is documented as needing a re-pair after a migration, so plan to run hermes whatsapp again.
Ready to move? Take the full backup today and book a free AI strategy session if you want help with the rest.
