A Hermes Agent backup is a copy of your ~/.hermes folder, and Hermes ships two built-in commands that make one for you: hermes backup for the whole install and hermes profile export for a single agent.
The full backup is a zip that includes your API keys, and the profile export is a smaller archive that strips them out.
This is the operator walkthrough, so you get every command in order for backing up, restoring, moving to a new Mac or a VPS, scheduling it and rolling back after a bad update.
I have run the profile export and import end to end on my own machine, and I documented that run in my portable Hermes agents guide.
The full-backup commands below come from the official Hermes docs and from the CLI help on Hermes Agent v0.21.4, and I'll say so where it matters.
What A Hermes Agent Backup Actually Protects
Hermes Agent is the free, open-source agent from Nous Research, and everything that makes your copy of it yours lives in one folder.
That folder is ~/.hermes, which the docs call the Hermes home.
The official configuration docs list what sits inside it.
| Item | What it holds | Does it hold secrets? |
|---|---|---|
config.yaml |
It holds your settings, such as the model, the terminal and the tools. | It can hold paths and provider names, but keys belong in .env. |
.env |
It holds your API keys. | Yes, this file is all secrets. |
auth.json |
It holds OAuth logins for providers such as Nous Portal. | Yes, this file is all secrets. |
SOUL.md |
It holds the agent's identity and personality. | No, unless you wrote something private into it. |
memories/ |
It holds the built-in memory files, MEMORY.md and USER.md. | It holds personal facts about you and your business. |
skills/ |
It holds the skills your agent has learned or installed. | No, unless a skill has a key pasted into it. |
cron/ |
It holds your scheduled jobs. | No. |
sessions/ and state.db |
They hold your conversation history. | They hold whatever you typed into a chat. |
plugins/ |
It holds the plugins you installed. | No. |
profiles/<name>/ |
Each named profile is its own smaller Hermes home with the same files. | Each profile has its own .env and auth.json. |
logs/ |
It holds error and gateway logs. | The docs say secrets are auto-redacted in logs. |
I'm showing you the documented layout here and not my own files, because my folder has client details in it.
The point of the table is simple.
Two files hold keys, three areas hold personal information, and the rest is the work you spent weeks tuning.
The Two Hermes Agent Backup Commands
Hermes gives you two tools, and they do different jobs.
The official FAQ compares them directly, and this is that comparison in my words.
hermes backup |
hermes profile export |
|
|---|---|---|
| Use it for | It is for a full machine backup or migration. | It is for moving or sharing one agent. |
| Scope | It covers the whole Hermes home, including every profile. | It covers one profile folder. |
| Credentials | It includes .env and auth.json. |
It always leaves .env and auth.json out. |
| Format | It writes a .zip file. |
It writes a .tar.gz file. |
| Restore command | You restore it with hermes import. |
You restore it with hermes profile import. |
The rule I use is easy to remember.
I use the full backup for myself and the profile export for anything another person will ever touch.
How To Run A Full Hermes Agent Backup
Step 1: Run The Command
Open a terminal and run this.
hermes backup
The docs say this saves a zip at ~/hermes-backup-<timestamp>.zip.
The docs also say the backup uses SQLite's backup API, so it produces a consistent snapshot even while Hermes is running.
Step 2: Choose Where It Goes
You can send the zip to a folder of your choice with the output flag.
mkdir -p ~/hermes-backups
hermes backup -o ~/hermes-backups/
The CLI help says --keep deletes older hermes-backup-*.zip files in that folder beyond the newest N, and the default is 3.
hermes backup -o ~/hermes-backups/ -k 8
Setting -k 0 keeps every backup.
Step 3: Read The Summary
The docs say a full backup reports any file that failed to copy.
An archive can exist with data missing, so read the skipped-file report before you trust it.
The command exits with status 1 when the backup is incomplete, which matters for the scheduled version later.
Step 4: Know What Is Left Out
The full backup is not an image of the app.
The docs list what it skips.
- It skips the Hermes source code, because you reinstall that.
- It skips dependency environments and downloaded tools, models and runtimes.
- It skips build caches, checkpoints, previous backups and quick snapshots.
- It skips browser profiles, including copies of real-browser credentials.
- It skips bytecode, SQLite sidecar files and process ID files.
Local model weights are in that list, so you download those again on a new machine.
The Quick Version
There is also a faster snapshot.
hermes backup --quick -l before-big-change
The CLI help says the quick snapshot only saves critical state files, which are config, state.db, .env, auth and cron.
The docs are clear that it is not a replacement for a full backup before a migration.
🔥 Want the backup job already wired into a full Agent OS? Inside the AI Profit Boardroom, I've got step-by-step Hermes tutorials plus the installable Agent OS, so your profiles, memory and scheduled jobs sit in one dashboard. You also get four coaching calls a week with 3,400+ members. → Get access here
How To Export One Hermes Profile
A profile is a separate agent with its own persona, skills, memory and schedule.
Exporting one is the part I have tested myself.
Step 1: List Your Profiles
hermes profile list
Step 2: Export The One You Want
hermes profile export my-agent -o ~/my-agent.tar.gz
If you leave -o off, read the path the command prints.
The v0.21.4 help says the default is a managed profile-exports/ folder under the Hermes home, with the profile name and a timestamp in the file name.
You can also type /export inside a Hermes chat, and the docs say the desktop app has it under ⌘K as "Export profile…".
Step 3: Look Inside Before You Share It
The docs give this exact check.
tar -tzf ~/my-agent.tar.gz | less
When I ran the export on one of my own profiles, the archive was 2.2 MB and held 712 files.
The profile I exported had a credentials file, and the archive had zero credential files in it.
That is the safety feature working as described.
There is one honest warning from the docs.
Credentials are removed, but an export can still contain memories/, sessions/ and USER.md, and nothing checks those for personal details you wrote yourself.
Read the file list before you send an export to anyone.
Step 4: Import It
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, so pass a new name in either case.
In my run the persona file matched exactly, the skills arrived, and the new profile showed up in hermes profile list straight away.
You then add your own keys once on that machine.
How To Restore A Full Backup
The docs warn you to stop the gateway before importing, so do that first.
hermes gateway stop
hermes import ~/hermes-backup-<timestamp>.zip
The docs say every file in the archive overwrites the matching file in your Hermes home.
The command asks for confirmation when Hermes is already installed there, and --force skips that prompt.
Two safety checks are built in, according to the CLI reference.
The archive is checked for damage before anything is written, and a damaged archive stops the import with your Hermes home untouched.
The import also warns you when an older backup replaces newer session data, so you know what you lost.
How To Move Hermes To A New Mac Or A VPS
This is the official migration recipe from the Hermes FAQ, with my notes added.
Step 1: Install Hermes On The New Machine
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
If you prefer Homebrew on a Mac, read my Hermes Agent brew guide first.
If you still need a server, my best Hermes Agent VPS ranking has the picks and the sizes.
Step 2: Back Up On The Old Machine
hermes backup
Step 3: Copy The Zip Across
scp ~/hermes-backup-<timestamp>.zip newmachine:~/
The zip contains your keys, so only copy it over an encrypted connection such as SSH.
Step 4: Import On The New Machine
hermes import ~/hermes-backup-<timestamp>.zip
Step 5: Check Keys And Providers
hermes setup
The docs tell you to run setup to verify that API keys and provider config work.
The docs also say you may need to update paths or re-authenticate with providers when the new machine is set up differently.
A Mac path such as /Users/you/vault will not exist on a Linux server, so fix any folder paths in your config.
If your terminal backend also changes on the server, my Hermes Agent backend guide covers those options.
Step 6: Stop The Old Machine Doing The Same Jobs
Your scheduled jobs travel inside the backup.
If both machines stay on, both will run them.
The CLI has an emergency stop for this, and the help text says it pauses cron dispatch and new gateway turns.
hermes pause
Run that on the old machine once the new one is confirmed working.
🚀 Ready to put Hermes Agent Backup to work in your business? Inside the AI Profit Boardroom you get step-by-step video trainings, my installable Agent OS and four coaching calls a week with 3,400+ members building real automations. → Join the AI Profit Boardroom
How To Schedule A Hermes Agent Backup
A backup you have to remember is a backup you will skip.
The simplest schedule is a normal system cron line, because hermes backup is an ordinary command.
Find the full path to Hermes first, because cron runs with a short path.
which hermes
crontab -e
Then add one line, with your own path in place of mine.
0 3 * * 0 /full/path/to/hermes backup -o "$HOME/hermes-backups/" -k 8
That runs every Sunday at 3am and keeps the newest eight zips.
The exit status I mentioned earlier is why this works well.
The docs say an incomplete backup exits with 1 and skips pruning, so older complete archives survive a bad run.
Hermes also has its own scheduler.
The CLI help for hermes cron create describes a --no-agent mode that runs a script from ~/.hermes/scripts/ on a schedule without calling a model.
I use the system cron line for backups, because I want the backup to run even when the agent itself is the thing that broke.
Copy at least one zip off the machine each week.
A backup on the same disk as the original does not survive a stolen laptop.
How To Roll Back After A Bad Hermes Update
Hermes already protects you here by default, which most people don't know.
The updating docs say hermes update takes a quick pre-update snapshot of selected state files for every profile.
Before You Update
hermes update --check
hermes update --backup
The first command tells you whether an update exists without installing it.
The second forces a full backup zip before the update, on top of the quick snapshot.
You can make that the default with one config line.
updates:
pre_update_backup: full
If The Update Breaks Something
The docs say Hermes checks critical files after pulling new code and automatically rolls the code back if any fail to parse.
For your state, start hermes in a terminal and use the snapshot command.
/snapshot
/snapshot restore <id>
The slash command reference says /snapshot with no arguments lists your snapshots, and it only works in the CLI.
For a full restore, import the zip you took before the update.
The docs add one caution that I'd take seriously.
Rolling the code back is not a data rollback, because a newer release can migrate config or databases in ways older code cannot read.
Take a fresh backup of the current state before you restore an old one.
One naming trap is worth knowing.
The /rollback command and hermes checkpoints are about your project files, not about Hermes itself, and the docs say that feature is opt-in.
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 to a private repository, 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.
That means the private remote is the copy of your history.
Three built-in helpers sit next to this, according to the CLI help.
hermes skills list-modifiedlists the bundled skills you have edited.hermes skills snapshot exportwrites your installed skills to a file, andimportinstalls them from one.hermes syncis Skill Sync, which moves your own skills between your devices.
If you want to version a whole agent, the docs describe profile distributions, which publish a profile as a git repository.
hermes profile install github.com/you/research-bot --alias
hermes profile update research-bot
The docs say a distribution never ships credentials, memories or sessions.
The docs also warn that Hermes does not control git, so those exclusions are not applied when you run git add yourself.
Never commit .env or auth.json.
How To Back Up An Obsidian Memory Vault
My memory setup is the built-in memory plus an Obsidian vault, which I rank first in my best Hermes Agent memory guide.
A vault is a normal folder that lives outside ~/.hermes.
Neither Hermes command backs it up.
The built-in MEMORY.md and USER.md files are inside the Hermes backup, and the vault is not.
A vault is plain text, so a private git repository is the easiest 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.
🔥 Want me to check your backup and migration plan live? Inside the AI Profit Boardroom, you can share your screen on one of four coaching calls a week and get your profiles, memory vault and server setup looked at. There are 3,400+ members building the same stack. → Join the AI Profit Boardroom
The Hermes Agent Backup Restore Test Checklist
A backup you have never restored is only a guess.
Run this list on the restored machine, or on a spare profile.
| Check | Command | What you want to see |
|---|---|---|
| Hermes runs | hermes --version |
You see a version number. |
| Health is clean | hermes doctor |
You see no blocking errors. |
| Profiles arrived | hermes profile list |
You see every profile you expect. |
| Skills arrived | hermes skills list |
You see your own skills in the list. |
| Jobs arrived | hermes cron list |
You see your scheduled jobs. |
| History arrived | hermes sessions list |
You see recent sessions. |
| Keys work | hermes setup |
Your provider and model respond. |
| The agent answers | hermes |
A test question gets a normal reply. |
| Components are up | hermes status |
The gateway and scheduler show the state you expect. |
I also open the memory folder and confirm the two memory files are there.
If you set Hermes up in one click on a host template, run the same list after the import.
Frequently Asked Questions
How do I back up Hermes Agent?
Run hermes backup in a terminal.
It writes a zip of your Hermes home to your home directory, and hermes profile export does the same job for one profile without the keys.
Does a Hermes Agent backup include my API keys?
The full backup zip includes .env and auth.json, so store it like a password file.
A profile export always leaves both files out.
How do I restore a Hermes Agent backup?
Stop the gateway and run hermes import with the path to the zip.
Use hermes profile import with a --name for a single profile archive.
How do I move Hermes Agent to a new Mac or a VPS?
Install Hermes on the new machine, back up on the old one, copy the zip with scp, import it and run hermes setup.
Pause the old machine afterwards so scheduled jobs don't run twice.
Is my Obsidian memory vault inside the Hermes backup?
No, because the vault lives outside the Hermes home folder.
Back it up separately with a private git repository.
Also On Our Network
- 🌐 How a business protects weeks of agent work with a backup routine
- 🌐 Every Hermes backup method scored in one reference
- 🌐 The five-minute Hermes backup quick-start for Agent OS users
- 🌐 What moves with a backup and which model to pair after a restore
📺 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 Goldie Agency into a seven-figure SEO and link building agency.
- I've grown my YouTube channel to 400,000+ subscribers.
- I run GoldieBench, where I score AI models on real one-shot builds.
- I wrote "Link Building Mastery", which is available on Amazon.
→ Get my best AI training inside the AI Profit Boardroom
Run the full backup tonight, restore it once to prove it works, and you'll have a Hermes Agent backup you can actually trust.
