Field notes · AI agents, Hermes & Claude Code By Julian Goldie

Migrate Hermes Agent To New Machine: The 7-Step Backup And Import Run (2026)

Two commands do the moving. Seven steps make sure nothing breaks. Here is the exact order, with the flags and the gotchas.

Get The AI Profit Stack Join AIPB →
  • 01 1,000+ done-for-you AI agent workflows
  • 02 5 live coaching calls / week with me
  • 03 7-day refund, cancel anytime
  • 04 3,400+ AI operators inside

To migrate Hermes Agent to new machine hardware, you run two commands that matter: hermes backup on the old box and hermes import on the new one.

Book a free SEO strategy session →

Everything else is checking: the vault key before, the exit code in the middle, and hermes setup at the end.

This is the exact order I'd run it in, with the flags, the file paths and the gotchas that catch people out.

If you'd rather have my team look over your move plan first, book a free SEO strategy session and bring your current setup notes.

The Whole Move On One Screen

Here's the full run before we go step by step.

# old machine
hermes vault key                         # where is the vault key?
hermes vault key migrate --to file       # only if it's in the keychain
hermes backup                            # writes ~/hermes-backup-<timestamp>.zip
scp ~/hermes-backup-<timestamp>.zip newmachine:~/

# new machine
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
# stop any running gateway first
hermes import ~/hermes-backup-<timestamp>.zip
hermes setup

That sequence comes straight from the Hermes FAQ section "Exporting Hermes to another machine", plus the vault step from the credential vault docs.

The FAQ's own scenario is moving skills, cron jobs and memories to a new dedicated Linux box.

Before You Start: Three Things To Check On The Old Box

First, know what you're moving.

A full backup covers config, credentials, memories, skills, sessions and profiles under the Hermes data root.

Second, know what you're not moving.

The CLI reference lists the exclusions: the hermes-agent code, dependency environments, models/, runtimes/, node/, checkpoints/, browser profiles, regenerable cache entries and previous backups.

Third, list your messaging channels.

WhatsApp, Telegram and any other paired channel are the things most likely to need attention after the move.

Step 1: Move The Vault Key Out Of The Keychain

Run hermes vault key to see where the key lives today.

By default it's a file at ~/.hermes/vault/vault.key, next to the encrypted vault.

If you switched it to the operating system keychain, the docs warn that backups and copied folders hold the vault without its key.

So before the backup, run hermes vault key migrate --to file.

The docs pair it with hermes vault key migrate --to keychain, so you can switch back once the move is done.

Book a free SEO strategy session →

Skip this and you'll land on the new machine with a vault you can't open.

Step 2: Take A Full Backup, Not A Quick One

Run plain hermes backup.

It writes ~/hermes-backup-<timestamp>.zip by default; add -o <path> to put it on an external drive instead.

You can leave Hermes running while it works.

The backup uses SQLite's backup() API, which the docs describe as WAL-safe.

Don't use --quick for this.

Quick mode saves only critical state (config.yaml, state.db, .env, auth and cron jobs), and the FAQ says it doesn't replace a full backup before a machine migration.

--keep N (default 3) prunes older full backups, so if you want to hold an extra copy, move it out of the way first.

🔥 Moving your Hermes setup onto a VPS this month? Inside the AI Profit Boardroom you get step-by-step video trainings on Hermes, the installable Agent OS, four coaching calls a week and 3,400+ members swapping notes on their own server setups. → Join the AI Profit Boardroom

Step 3: Read The Exit Code Before You Copy Anything

This is the step people skip.

  • 0: every file landed in the zip.
  • 1: "Backup incomplete". The zip is kept, but some files were skipped, and --keep pruning doesn't run.
  • 2: another backup was already running.

Check it in your shell straight after the run, before you open another window.

On a 1, read the skipped-file report and fix what it names before going further.

The docs are direct about this: review the report before you remove the source install.

Step 4: Install Hermes On The New Machine

The FAQ installs with the script:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installation page also documents desktop packages for macOS and Windows.

That page has a tip for exactly this case: if you already run Hermes elsewhere, restore with hermes import instead of rebuilding from scratch.

Don't spend time configuring the fresh install by hand. The import will overwrite it.

Step 5: Copy The Zip And Stop The Gateway

Copy the archive across however you like. The FAQ example is scp.

Book a free SEO strategy session →

Then, on the new machine, stop any gateway that's running.

The CLI reference puts this in a warning box: stop the gateway before importing to avoid conflicts with running processes.

A freshly installed box may not have one running yet, but check anyway if you ran setup during the install.

Step 6: Import, Then Run Setup

hermes import ~/hermes-backup-<timestamp>.zip
hermes setup

The import overwrites existing files in the Hermes home.

If a Hermes installation is already there, it asks you to confirm; -f / --force only skips that prompt.

Before writing a single file, it decompresses every member and checks its CRC.

A damaged zip leaves the home untouched and exits 1, so a bad copy can't half-overwrite your new box.

Then hermes setup checks your API keys and provider config, which is the FAQ's final step.

Watch the session warning

Databases such as state.db, kanban.db and response_store.db are written into the existing database file rather than swapped in.

If the imported state.db holds fewer messages than the one it replaced, the summary prints a warning with before and after counts.

On a new machine you'd expect the opposite, so if you see it, you probably copied an older zip.

Step 7: Bring Back The Services

If the old box ran the gateway as a service, set it up again with hermes gateway install.

The command is in the docs; needing it after a move is my reading, since the backup leaves out gateway.pid and the service lives outside the Hermes home.

For WhatsApp, plan to re-pair with hermes whatsapp.

The import guide notes that WhatsApp authenticates through Baileys QR pairing and needs re-pairing after a migration.

📞 Want my team to sanity-check your move plan? Book a free SEO strategy session and we'll go through what runs on your old box and what needs re-pairing on the new one. → Book your free session

Moving To A VPS: The Extra Bits

A VPS move is the same seven steps with a few practical additions.

Make sure you can SSH into the server as the user who will run Hermes, because the zip restores into that user's Hermes home.

Book a free SEO strategy session →

Run the install script as that same user, not as a different account, so the paths line up with what the import expects.

Copy the zip with scp straight into that user's home folder, which is where the FAQ example puts it.

On a headless server, the desktop packages don't apply, so the script install is the one to use.

And if the gateway is going to run around the clock, install it as a service once the import and setup pass.

The FAQ's own scenario is a dedicated Linux box, so this is the path the docs had in mind.

What The Backup Leaves Out, And Why That's Fine

The exclusions look long, but each one has a reason.

The hermes-agent code and dependency environments come from the installer on the new machine.

Downloaded models and runtimes are left out because they're large; the docs say runtime downloads are often tens of GB.

SQLite -wal, -shm and -journal sidecars regenerate locally.

gateway.pid and cron.pid belong to the old machine's running processes and would be wrong on the new one.

Browser profiles stay behind, which also keeps copies of real-browser credentials out of the zip.

From cache/, the backup keeps images, audio, videos, documents, screenshots and citations, so the files your agent produced aren't lost.

Why I Never Reach For hermes migrate Here

The name sounds right. It isn't.

hermes migrate imports from other agents: OpenClaw, Claude Code, Codex, Cursor, Grok Bot and OpenBot.

It also rewrites config, with migrate xai and migrate relay.

Since v0.23.0 those importers live in the agent-importers plugin.

If you're bringing Bots over from Grok Bot, that's its own process, and I wrote it up in the guide to migrate Grok Bot to Hermes.

Hermes to Hermes is always backup plus import.

One Agent Only? Use A Profile Export

Sometimes the whole install stays put and only one agent moves, say a support profile heading to a VPS.

# old machine
hermes profile export work ./work-backup.tar.gz

# new machine
hermes profile import ./work-backup.tar.gz work

Profile exports always strip auth.json, .env, OAuth and bot token files, mcp-tokens/, vault/, platform sessions and pairing stores.

Book a free SEO strategy session →

So plan to add credentials again on the target.

The import refuses to overwrite an existing profile and can't import as default.

In a chat you can use /export, and on desktop it's ⌘K → Export profile…, per the profile distributions page.

If you use Honcho or another memory provider, rerun hermes honcho setup or hermes memory setup after the import.

The rsync Fallback And When I'd Skip It

The FAQ gives a manual route too:

rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

It works, but you lose the exit codes, the CRC test and the session warning.

I'd only use it when I'm syncing to a box I control end to end and I'm happy to verify by hand.

The keychain rule still applies: a copied folder doesn't carry a keychain vault key.

Profile Exports Vs Profile Distributions

The profile docs mention a third tool, and it's easy to mix up with exports.

hermes profile install pulls a profile from a git repo, and hermes profile update refreshes it.

That's built for deploying the same agent to several machines, and it never ships memories, sessions, state.db, .env or auth.json.

For moving one profile with its history, the docs point you to /export instead.

Gotchas I'd Watch For

  • Old zip, new box. Grab the newest backup, not the one sitting in Downloads from last month.
  • Paths. The FAQ says you may need to update paths if the new machine has a different setup.
  • Provider logins. The same section says you may need to re-authenticate with providers.
  • Different operating systems. The docs don't cover moving between operating systems, so test carefully if you're doing that.
  • Update backups. The updating page says pre-update backups protect an in-place update; they're not your migration tool.

My Post-Move Checklist

  1. Backup exited 0, or the skipped-file report has been read.
  2. Import finished with no "Import incomplete" line.
  3. hermes setup passes for every provider.
  4. An old session opens and memories show up.
  5. Skills and cron jobs are listed.
  6. The gateway service is installed and running.
  7. Messaging channels are re-paired and answering.
  8. The vault opens.

Only then do I touch the old box.

If you want to go deeper on Hermes setups like this, the AI Profit Boardroom has the full trainings and the Agent OS.

Book a free SEO strategy session →

Also On Our Network

FAQ: Migrate Hermes Agent To New Machine

Which exit code means my Hermes backup is safe to use?

Exit code 0 means every file landed in the zip. Exit code 1 means some files were skipped, so read the skipped-file report first. Exit code 2 means another backup was already running.

Do I need to stop Hermes before running hermes backup?

No. The backup uses SQLite's backup API, which the docs call WAL-safe. You do need to stop the gateway on the new machine before running hermes import.

What does hermes import --force do?

It only skips the confirmation prompt that appears when the target already has a Hermes installation. The import overwrites existing files either way.

Can I use hermes backup --quick before a move?

No. Quick mode saves only critical state, and the Hermes FAQ says it is not a replacement for the full backup before a machine migration.

What happens if the zip gets damaged in transit?

hermes import checks the CRC of every member before writing anything. A damaged archive leaves the Hermes home untouched and exits 1.

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

About Julian

I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.

I help business owners scale with AI agents, automation and SEO.

  • I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
  • I've grown a YouTube channel to 400,000+ subscribers.
  • I wrote "Link Building Mastery".
  • My Udemy courses have taught over 29,000 students.

→ Get my best AI training inside the AI Profit Boardroom

Take the full backup tonight, check the exit code, and if you want a hand with the rest, book a free strategy session and we'll plan how you migrate Hermes Agent to new machine hardware without losing a session.

§ Field reports

Real wins from inside the AI Profit Boardroom

See all 3,400+ members →
AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot AIPB member win screenshot

Scroll sideways →

⚑ Next step

Ready to run AI agents that actually do the work?

Join 3,400+ operators inside the AI Profit Boardroom. Get 1,000+ plug-and-play AI agent workflows, 5 coaching calls a week, and a community that holds you accountable.

Join The AI Agent Community →

7-day no-questions refund · Cancel anytime

Found this useful? Get more of this site in your Google.

One tap adds us as a preferred source — Google then shows you our posts more often in Search, Top Stories, and AI Overviews.

← Back to all posts