agentos.guide › blog

Hermes Agent Backup: The Five-Minute Quick-Start, The Restore Steps And Where It Fits In An Agent OS

By Julian Goldie · 7 October 2026 · agentos.guide

A Hermes Agent backup is a copy of your ~/.hermes folder, and Hermes gives you two built-in commands to make one: hermes backup for everything and hermes profile export for one agent.

The full backup keeps your API keys inside the zip, and the profile export strips them out so the file is safe to share.

Below you'll get a five-minute quick-start, the restore and migration steps, a schedule, a rollback plan and how backup fits into a full Agent OS.

What a Hermes Agent backup is

Hermes Agent is the free, open-source agent from Nous Research.

Everything that makes your install yours sits in one folder, which the docs call the Hermes home.

The official configuration docs list what is inside that folder.

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

Two of those items hold keys, three hold personal information, and the rest is the work you spent weeks tuning.

A backup is how you stop one broken laptop from deleting all of it.

The two Hermes Agent backup commands

Hermes has two built-in tools, and the official FAQ compares them.

My rule is short.

I use the full backup for myself and the profile export for anything another person will touch.

I have run the export and import end to end, and I wrote that run up in my portable Hermes agents guide.

The full-backup details below come from the official docs and the CLI help on Hermes Agent v0.21.4.

The five-minute Hermes Agent backup quick-start

Minute 1: take a full backup

hermes backup

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

The docs also say it is safe to run while Hermes is working, because it copies databases with SQLite's backup API.

Read the summary it prints, because the docs say files that fail to copy are reported there.

Minute 2: send it to a backup folder and keep eight

mkdir -p ~/hermes-backups

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

The CLI help says -k deletes older backup zips in that folder beyond the newest N, and the default is 3.

Minute 3: export the one agent you care about most

hermes profile list

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

You can also type /export inside a Hermes chat.

The docs say the desktop app has the same thing under ⌘K as "Export profile…".

Minute 4: look inside the export

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

When I ran this on one of my profiles, the archive was 2.2 MB and held 712 files.

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

The docs warn that an export can still include your memories, your sessions and your USER.md file.

Nothing scans those for personal details, so read the list before you share the file.

Minute 5: put a copy somewhere else

Copy the newest zip to a second location, such as an encrypted external drive.

The full zip contains your keys, so treat it like a file of passwords.

A backup that sits on the same disk as the original does not survive a stolen laptop.

🔥 Want the exact Hermes setup I run inside my Agent OS?

Inside the AI Profit Boardroom you get the installable Agent OS, step-by-step video tutorials, four coaching calls a week and 3,400+ members building real automations.

→ Get access here

How to restore a Hermes Agent backup

The docs warn 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.

It asks for confirmation when Hermes is already installed there, and --force skips that question.

The archive is checked for damage before anything is written.

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

A single profile comes back with its own command.

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

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

You add your own keys once on that machine, because the export left them behind.

How to move Hermes to a new Mac or a VPS

The official FAQ gives the recipe, and I've added the parts people forget.

• Install Hermes on the new machine with the official install script first.
• Run hermes backup on the old machine.
• Copy the zip across with scp, which keeps your keys on an encrypted connection.
• Run hermes import on the new machine.
• Run hermes setup to verify that your keys and provider config still work.

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 on the new machine.

A Mac folder path will not exist on a Linux server, so check any paths in your config.

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

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

I'd run that on the old machine once the new one is confirmed working.

My best Hermes Agent VPS guide covers which server to pick.

My Hermes Agent brew guide covers the Mac install, and my Hermes Agent backend guide covers where commands run after the move.

How to schedule a Hermes Agent backup

A backup you have to remember is a backup you'll skip.

The command is an ordinary one, so a normal system cron line can run it.

which hermes

crontab -e

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.

The docs say an incomplete backup exits with an error and skips the clean-up, so a bad run never deletes your last good archive.

Hermes has its own scheduler too.

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

I'd still use the system scheduler for backups, because the backup should run even when the agent is the thing that broke.

How to roll back after a bad Hermes update

Hermes protects you here by default.

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

Those files include your config, your keys, your cron jobs and your pairing data.

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

hermes update --check

hermes update --backup

A config setting makes the full backup the default.

updates:
  pre_update_backup: full

The docs say Hermes checks its critical files after pulling new 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 then type /snapshot restore <id> to go back to one.

The docs add a caution that I take seriously.

Rolling the code back is not a data rollback, because a newer release can migrate your data in ways older code cannot read.

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

The /rollback command is a different feature, because it protects your project files and not Hermes itself.

🔥 Want the exact Hermes setup I run inside my Agent OS?

Inside the AI Profit Boardroom you get the installable Agent OS, step-by-step video tutorials, four coaching calls a week and 3,400+ members building real automations.

→ Get access here

How to version Hermes skills with git

Skills are plain files in a folder, so git works on them directly.

cd ~/.hermes/skills

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

Push that to a private repository and never a public one.

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 lists three helpers that sit next to this.

• hermes skills list-modified lists the bundled skills you have edited.
• hermes skills snapshot export writes your installed skills to a file.
• hermes sync is Skill Sync, which moves your own skills between your devices.

The docs also describe profile distributions, which publish a whole agent as a git repository.

A distribution never ships credentials, memories or sessions, according to the docs.

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

Where a Hermes Agent backup fits in an Agent OS

An Agent OS is more than one folder, and that is where people get caught out.

My Agent OS is a dashboard running a crew of agents under one shared memory.

I keep one Hermes profile per model inside it, so I have several profiles and not one.

That changes how I think about backup.

The full backup is the right tool for the brain layer, because it captures every profile in one file.

The profile export is the right tool when I want to hand one tuned agent to somebody else.

The memory layer is the one a Hermes backup misses.

How to back up an Obsidian memory vault

My shared memory is an Obsidian vault, and I explain the setup in my Hermes second brain guide.

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

Neither Hermes command backs it up.

The built-in memory files are inside the Hermes backup, and the vault needs its own.

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 memory vault is full of personal and client detail.

My best Hermes Agent memory ranking explains why the vault is my top memory pick.

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 folder outside the Hermes home.

The full backup does include your keys, which is the one thing to remember when you store it.

The restore test checklist

A backup you have never restored is only a guess.

Run this list on the restored machine, or after importing into a spare profile.

I also open the memory folder and confirm the two memory files are there.

FAQ

How do I back up Hermes Agent?

Run hermes backup in a terminal. The docs say it writes a zip of your Hermes home to your home directory, covering config, skills, memories, sessions, cron jobs, every profile and your credentials. Use hermes profile export with a profile name when you only want one agent without its keys.

Does a Hermes Agent backup include API keys?

The full hermes backup zip includes the .env and auth.json files, so store it like a password file. A hermes profile export archive always excludes both files.

How do I restore a Hermes Agent backup?

Stop the gateway, then run hermes import with the path to the zip. For a single profile archive, run hermes profile import with the path and a --name for the new profile.

How do I move Hermes Agent to a new Mac or a VPS?

Install Hermes on the new machine, run hermes backup on the old one, copy the zip with scp, run hermes import on the new machine and then run hermes setup to check your keys and providers.

Does Hermes back up before an update?

Yes. The docs say hermes update saves a quick snapshot of selected state files for every profile by default, and hermes update --backup adds a full zip.

Is an Obsidian vault included in a Hermes backup?

No. A vault lives outside the Hermes home folder, so back it up separately, for example with a private git repository.

Final word on Hermes Agent backup

Run the five-minute quick-start today, and then restore it once so you know it works.

Add the weekly schedule and a private repository for your vault, and you'll have a complete Hermes Agent backup.

Related guides on agentos.guide

→ Hermes AI Agents Just Went Portable

→ Hermes AI + Obsidian: Build The Ultimate AI Second Brain (Free)

→ Best Hermes Agent VPS? My Pick + Server Quick-Start

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

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

← all guides on agentos.guide