How to Migrate and Back Up Your Hermes Agent Profile to Another Host

Your Hermes agent has been running for weeks. Maybe months. Skills installed, memories loaded, cron jobs firing on schedule, config tuned just right.

Now you need to move it to a new server.

Or you want a backup before a risky upgrade. A clone for testing. Whatever the reason, the question is the same: how do you pick up an entire agent and put it down somewhere else without breaking it?

Hermes has two commands for this. profile export packs everything into a tar.gz. profile import unpacks it on the other end. Simple in theory. But if you run them without knowing what gets packed and what gets left behind, you will spend your afternoon debugging.

The quick version

Two commands.

# On the old server
hermes profile export cto -o cto-backup.tar.gz

# Transfer the file, then on the new server
hermes profile import cto-backup.tar.gz --name cto

Skills, memories, sessions, config. All carried over.

Except the parts that are not. And those parts are the ones that bite you.

What goes into the archive (and what does not)

Hermes is selective. It packs your configuration, personality, skills, memory, and history. It deliberately leaves out anything that holds a secret. I verified this by exporting a real profile and inspecting the tar contents.

Those two "No" rows are the whole point of this article. Your .env file holds every API key your agent uses. Your auth.json holds OAuth tokens. Neither goes into the archive. This is a deliberate design decision, not an oversight. If those files were bundled into a tar.gz that someone accidentally uploaded to a public bucket, that would be a very bad Tuesday.

Seven things that can go wrong

1. Your API keys are gone

After importing, the agent has no keys. It will fail on the first inference call. You need to set up .env manually on the new host.

# Copy via a secure channel
scp ~/.hermes/profiles/cto/.env newserver:/opt/data/profiles/cto/.env

Do not skip this. An agent without keys looks alive but produces nothing.

2. Absolute paths break

Config files accumulate hard-coded paths over time. A script at /opt/data/scripts/env_loader.py on your old server might need to live at /home/aji/scripts/env_loader.py on the new one. After import, open config.yaml and search for every path. Fix them.

3. The model might not be reachable

Your config specifies which model and provider to call. If the new host has a different network setup, routes through a different VPN, or uses a different billing account with the provider, inference calls will fail. Send a test message right after import to catch this early.

4. Docker paths differ from bare-metal

If you export from a bare-metal install and import into Docker, every path shifts. /opt/data/ becomes /data/. Mount points change. Volume names change. Budget fifteen minutes to fix these after import.

5. Cron jobs reference host-specific things

Cron jobs often call local endpoints or reference scripts by absolute path. After import, open every cron job and check that the paths and URLs still resolve on the new host.

6. SQLite and concurrent access

The state database runs in WAL mode. If you export while the agent is mid-conversation, you might capture an inconsistent snapshot. The fix is simple: stop the gateway before exporting.

7. OAuth tokens are not portable

Even if auth.json were included, the tokens inside expire quickly. You need to re-authenticate on the new host:

hermes login --provider nous

When you would actually use this

Backups. Run a nightly export as a cron job. If the server dies, you restore from last night's archive and lose at most 24 hours.

0 3 * * * hermes profile export cto -o /backups/cto-$(date +%Y%m%d).tar.gz

Server migration. I used this to move from an Oracle ARM box to a Hetzner box recently. Export, scp the archive, import, fix paths, re-login. The whole thing took 12 minutes.

Dev and staging clones. Want to test a config change without breaking production? Export the profile, import it under a different name, and experiment freely.

hermes profile export cto -o /tmp/cto-test.tar.gz
hermes profile import /tmp/cto-test.tar.gz --name cto-staging

Team templates. Export your carefully tuned profile and share the tar.gz with a teammate. They import it, add their own keys, and start from your baseline instead of from scratch.

Pre-upgrade snapshots. Before a Hermes version bump or a risky config refactor, take a snapshot. If something breaks, you roll back to the archive.

Post-import checklist

Run through this every time. Skipping steps here is how you end up with an agent that looks fine but silently fails on its first real task.

1. Set up .env with all provider keys. Use a secure transfer method.
2. Run hermes login --provider nous for fresh OAuth tokens.
3. Open config.yaml and fix every absolute path.
4. Send a test message to verify inference works end to end.
5. Check each cron job for broken paths or dead endpoints.
6. Load two or three skills to confirm they still work.
7. Start the gateway and verify your messaging platform connects.

Best practices

Export when idle. Not while a conversation is active. SQLite WAL consistency depends on it.

Version your backups. Use dates in filenames. Keep at least seven days of history.

Test your restores. A backup you have never restored from is not a backup. It is hope. Do a dry-run restore once a month.

Transfer securely. The tar.gz contains memories and session history. Use scp or an encrypted channel, not plain HTTP.

Sources

Hermes Agent docs: Profiles (official documentation by Nous Research)

Hermes Agent CLI reference

Hermes Agent on GitHub

Commands and behaviors described here were verified against hermes profile export --help and hermes profile import --help on a live Hermes install.

The one thing to remember

Forget everything else if you want. But remember this: .env does not come with the export. That is not a bug, it is a security feature. Manual key setup is a small price for keeping your secrets out of transferable archive files.