Hermes Agent Backup: What Moves With You, What Stays Behind, And Which Model To Plug Back In

A Hermes Agent backup is a copy of the ./.hermes folder, and Hermes has two built-in commands that create one: hermes backup for the whole install and hermes profile export for a single agent.

The full backup carries your API keys, and the profile export deliberately leaves them behind.

Hermes Agent is the free, open-source agent from Nous Research, and that one folder holds its persona, skills, memory, history and schedule.

I'll explain what moves and what doesn't first, then the backup, restore and migration steps, and only at the end which models to plug back in.

I have run the profile export and import myself, and the full-backup details come from the official docs and the CLI help on v0.21.4.

What moves and what doesn't in a Hermes Agent backup

That table is the whole idea of this page.

The work you tuned travels, the regenerable parts stay, and your keys only travel in the file meant for you.

What a Hermes Agent backup is protecting

The official configuration docs list what sits inside the Hermes home.

• The config.yaml file holds your settings, such as the model, the terminal and the tools.
• The .env file holds your API keys.
• The auth.json file holds OAuth provider logins.
• The SOUL.md file holds the agent's identity.
• The memories/ folder holds the built-in MEMORY.md and USER.md files.
• The skills/ folder holds the skills the agent made or installed.
• The cron/ folder holds your scheduled jobs.
• The sessions/ folder and the state.db database hold your conversation history.
• The plugins/ folder holds installed plugins.
• The profiles/ folder holds each named profile, with the same layout inside.

I'm describing the documented layout and not showing my own files.

Two of those items are pure secrets, which are .env and auth.json.

The memory and the sessions are personal, and the rest is your tuning work.

How the two Hermes Agent backup commands work

The full backup

hermes backup

The docs say this writes a zip to ~/hermes-backup-<timestamp>.zip.

The CLI reference says it copies databases with SQLite's backup API, so it works while Hermes is running.

You can choose the folder and how many old backups to keep.

hermes backup -o ~/hermes-backups/ -k 8

The CLI help says -k keeps the newest N zips in that folder, and the default is 3.

The docs say the command exits with an error when some files could not be added, and that pruning is skipped in that case.

There is also a quick mode.

hermes backup --quick -l before-big-change

The help text says the quick snapshot only covers config, state.db, .env, auth and cron.

The docs say it is not a replacement for a full backup before a migration.

The profile export

hermes profile export my-agent -o ~/my-agent.tar.gz

The profile command docs say auth.json and .env are always excluded.

You can also type /export in a Hermes chat, and the docs say the desktop app has it under ⌘K.

When I exported one of my own profiles, the archive was 2.2 MB and held 712 files.

My source profile had a credentials file, and the archive held zero credential files.

I documented that run in my portable Hermes agents guide.

The docs give one honest warning.

An export can still contain your memories, your sessions and your USER.md file, and nothing scans those for personal details.

List the contents before you send it to anyone.

tar -tzf ~/my-agent.tar.gz | less

How to restore a Hermes Agent backup

The docs tell you to stop the gateway before you import.

hermes gateway stop

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

The CLI reference says every file in the archive overwrites the matching file in your Hermes home.

The command asks before overwriting an existing install, and --force skips that question.

The archive is checked for damage before anything is written.

The import warns you when an older backup replaces newer session data.

A single profile has its own restore command.

hermes profile import ~/my-agent.tar.gz --name my-agent

The docs say it refuses to overwrite an existing profile and cannot import as default.

You then add your own keys on that machine.

How to move Hermes to a new Mac or a VPS

The official FAQ has a migration recipe, and these are its steps.

• You install Hermes on the new machine with the official install script.
• You run hermes backup on the old machine.
• You copy the zip to the new machine with scp.
• You run hermes import on the new machine.
• You run hermes setup to verify your keys and provider config.

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

scp ~/hermes-backup-<timestamp>.zip newmachine:~/

The docs say you may need to update paths or sign in to providers again.

A folder path from a Mac will not exist on a Linux server.

Your scheduled jobs travel inside the backup, so two live machines would both run them.

The CLI has hermes pause, which the help text describes as an emergency stop for cron dispatch and new gateway turns.

I'd run it on the old machine once the new one works.

You can read my best Hermes Agent VPS ranking for the server, my Hermes Agent brew guide for the Mac install and my Hermes Agent backend guide for where commands run afterwards.

How to schedule a Hermes Agent backup

The backup is an ordinary command, so a system cron line can run it every week.

which hermes

0 3 * * 0 /full/path/to/hermes backup -o "$HOME/hermes-backups/" -k 8

That line runs every Sunday at 3am and keeps the newest eight zips.

Hermes also has its own scheduler.

The help for hermes cron create describes a --no-agent mode that runs a script from ./.hermes/scripts/ without calling a model.

I prefer the system scheduler for backups, because the backup should still run when the agent is the thing that broke.

Copy one zip off the machine each week, and keep it somewhere encrypted because it holds your keys.

How to roll back after a bad Hermes update

The updating docs say hermes update saves a quick snapshot of selected state files for every profile by default.

You can check for an update first, and you can force a full zip before it.

hermes update --check

hermes update --backup

The updates.pre_update_backup config key takes quick, full or off.

The docs say Hermes validates its critical files after pulling code and rolls the code back automatically if they fail to parse.

For your state, start hermes in a terminal and type /snapshot to list snapshots.

You type /snapshot restore <id> to go back to one.

The docs warn that a code rollback is not a data rollback, because a newer release can migrate your data.

Take a fresh backup of the current state before you restore an older one.

The /rollback command is a separate, opt-in feature that protects project files and not Hermes itself.

How to version Hermes skills with git

Skills are plain files, so you can put the folder under version control.

cd ~/.hermes/skills

git init && git add . && git commit -m 'Skills snapshot'

Push to a private repository only.

I read the v0.21.4 backup code, and it skips nested .git folders, so your git history is not inside the backup zip.

The CLI help also lists hermes skills list-modified, hermes skills snapshot export and hermes sync, which is Skill Sync between your devices.

The docs describe profile distributions too, which publish a whole agent as a git repository without credentials, memories or sessions.

The docs warn that Hermes does not control git, so never commit .env or auth.json yourself.

How to back up an Obsidian memory vault

I run Hermes with an Obsidian vault as shared memory, and it is my top pick in my best Hermes Agent memory ranking.

A vault is a normal folder that lives outside ~/.hermes.

Neither Hermes command backs it up.

A vault is plain text, so a private git repository is the simplest backup.

cd /path/to/your/vault

git init && git add . && git commit -m 'Vault snapshot'

Keep it private, because a vault is full of personal and client detail.

The Hermes Agent backup restore test checklist

A backup you have never restored is only a guess.

Which models to plug back in after a Hermes Agent backup restore

This is the part GoldieBench is for, so I'll be exact about what the data shows.

A Hermes Agent backup doesn't ship its own model, and the backup commands don't call a model at all.

Your model choice travels as a setting inside config.yaml.

The key for that model travels in a full backup and does not travel in a profile export.

Downloaded local model weights do not travel, because the docs say the backup skips downloaded models and runtimes.

That means a restore on a new machine ends with one decision, which is the brain you reconnect.

GoldieBench does not measure backup or restore.

It scores models on one-shot builds, so treat these live averages as a guide to general capability.

The practical point is about where you restore to.

A cloud model follows you to any machine, because all it needs is the key or the login.

A local model is tied to the hardware, so a move from a Mac to a small Linux server usually means switching that profile to a cloud model.

A profile export makes this obvious, because the new machine has no keys until you add them.

I keep one Hermes profile per model, so I can export or restore one brain's setup without touching the others.

You can compare more options in my best Hermes Agent model ranking, the best LLMs for Hermes Agent and the local models board.

What a Hermes Agent backup deliberately leaves out

• A profile export leaves out your API keys and logins, so a shared file cannot spend on your accounts.
• A full backup leaves out the Hermes source code, so you reinstall it first.
• A full backup leaves out dependency environments and downloaded tools, models and runtimes.
• A full backup leaves out caches, checkpoints, earlier backups and quick snapshots.
• A full backup leaves out browser profiles, including copies of real-browser credentials.
• Neither command includes a vault or any other folder outside the Hermes home.

The full backup does include your keys, so store that zip like a file of passwords.

Also On Our Network

• Agent Operatorsthe command-by-command Hermes backup and migration walkthrough
• AI Income Desksix business situations where a Hermes backup saves you
• AI Tool Verdictevery Hermes backup method scored in one verdict
• agentos.guidethe five-minute Hermes backup quick-start for an Agent OS
• agentos.guideMy real Hermes profile export and import run on agentos.guide

Take the full backup, test one restore, reconnect a model that suits the new machine, and you will have a working Hermes Agent backup.