Hermes Agent Backup, Restore & Safety Net: Never Lose Your Config

By Hermes Agent·Jul 5, 2026·10 min read·hermes tutorial backup checkpoints safety

Hermes Agent's three protection layers: quick snapshots (`--quick --label`) with `manifest.json` (8 files, state.db ~39 MB), full backups (`-o…

TLDR: Hermes Agent has three layers of data protection: hermes backup --quick for fast state snapshots (~10 MB, 8 files), hermes backup for full zip archives (everything under ~/.hermes/), and hermes checkpoints for automatic file versioning before destructive edits. Combined, they give you rollback at the config, session, and file-operation level.

Key Takeaways

hermes backup --quick --label "memo" — snapshot your config, state.db, .env, auth, and cron jobs in under a second
hermes backup -o ~/archive.zip — full zip backup of all Hermes data (skills, sessions, plugins, everything under ~/.hermes/)
State snapshots live in ~/.hermes/state-snapshots/<timestamp>-<label>/ — easy to restore manually
hermes checkpoints status — see how much disk your file-operation rollback history consumes
Checkpoints track every write_file, patch, and terminal edit — you can always revert
Combine backups with cron (hermes cron create) for automated daily snapshots

Why You Need a Safety Net

Hermes Agent stores everything under ~/.hermes/ — config profiles, session history, skills, plugins, MCP server registrations, cron job definitions, auth tokens, and the state database. If that directory gets corrupted (bad config write, disk full, accidental rm -rf), you lose weeks of customization.

Three independent protection layers exist, and they complement each other:

Layer	Scope	Automation	Restore Speed
`hermes backup --quick`	Critical state (8 files)	Manual or cron	Seconds (copy back)
`hermes backup` (full)	Everything in `~/.hermes/`	Manual	Minutes (unzip)
`hermes checkpoints`	Per-file before destructive edits	Automatic (always on)	Instant (`git checkout`)

Layer 1: State Snapshots with `hermes backup --quick`

The fastest way to protect your Hermes configuration. A quick snapshot captures exactly the files needed to reconstruct your agent identity:

config.yaml — model, agent, terminal, compression, memory settings
state.db — session history, memory store, conversation state
.env — API keys, tokens, secrets
auth.json — authenticated platform credentials
cron/jobs.json — scheduled job definitions
gateway_state.json — messaging gateway runtime state
channel_directory.json — platform channel mappings
processes.json — running background process registry

Creating a Snapshot

hermes backup --quick --label "pre-upgrade"

Output:

State snapshot created: 20260706-171230-pre-upgrade
  4 snapshot(s) stored in ~/.hermes/state-snapshots/
  Restore with: /snapshot restore 20260706-171230-pre-upgrade

The snapshot writes a directory with a human-readable timestamp and your label:

ls ~/.hermes/state-snapshots/20260706-171230-pre-upgrade/

auth.json              config.yaml            gateway_state.json
channel_directory.json cron/                  manifest.json
                      processes.json          state.db

Each snapshot includes a manifest.json that records file sizes and timestamps:

{
  "id": "20260706-171230-pre-upgrade",
  "timestamp": "20260706-171230",
  "label": "pre-upgrade",
  "file_count": 8,
  "total_size": 38985058,
  "files": {
    "state.db": 38916096,
    "config.yaml": 11623,
    ".env": 22097,
    "auth.json": 5835,
    "cron/jobs.json": 27888,
    "gateway_state.json": 405,
    "channel_directory.json": 644,
    "processes.json": 470
  }
}

The state.db dominates at ~39 MB for a typical install with months of session history. The remaining seven files are a few kilobytes each.

Restoring from a Snapshot

Restoration is manual (intentionally — to prevent accidental overwrites):

cp ~/.hermes/state-snapshots/20260706-171230-pre-upgrade/config.yaml ~/.hermes/config.yaml
cp ~/.hermes/state-snapshots/20260706-171230-pre-upgrade/state.db ~/.hermes/state.db
cp ~/.hermes/state-snapshots/20260706-171230-pre-upgrade/.env ~/.hermes/.env
cp ~/.hermes/state-snapshots/20260706-171230-pre-upgrade/auth.json ~/.hermes/auth.json
cp -r ~/.hermes/state-snapshots/20260706-171230-pre-upgrade/cron ~/.hermes/

For a full restore, stop the gateway first to prevent database corruption:

hermes gateway stop
# Restore files...
hermes gateway start

Layer 2: Full Backup Archives

When you need the complete picture — skills, plugins, session transcripts, everything under ~/.hermes/ — use the full backup:

hermes backup -o ~/hermes-full-2026-07-06.zip

This creates a zip archive of the entire Hermes data directory, excluding the hermes-agent Python package itself. The archive includes:

Directory	Contents
`config.yaml`	Main configuration
`.env`	Environment secrets
`state.db`	Sessions and memory
`auth.json`	Platform credentials
`skills/`	All installed skills
`plugins/`	All installed plugins
`profiles/`	Each profile’s full data
`cron/`	Cron job definitions
`memories/`	Long-term memory store
`state-snapshots/`	Previous quick snapshots
`checkpoints/`	File-operation rollback data
`logs/`	Gateway and agent logs

Note: A full backup can take 30+ seconds on a mature install because it zips potentially gigabytes of session data. The --quick variant finishes in under a second.

What the Full Archive Contains

unzip -l ~/hermes-full-2026-07-06.zip | head -40

A healthy backup should contain at minimum:

config.yaml
state.db
.env
auth.json
skills/
plugins/
profiles/default/

If any of these are missing, your backup is incomplete — run hermes doctor to check for issues.

Layer 3: Automatic File Checkpoints

This is the layer you didn’t know you needed until something goes wrong mid-edit. Every time Hermes calls write_file, patch, or a terminal command that writes to disk, the checkpoint system takes a snapshot of the affected files before the operation.

Checkpoints live in a shadow git repository under ~/.hermes/checkpoints/. Each project directory gets its own virtual branch.

Checking Checkpoint Status

hermes checkpoints status

Output:

Checkpoint base: /home/you/.hermes/checkpoints
Total size:      142 MB
  store/         142 MB
  legacy-*       0 B
Projects:        12

Projects:
  /home/you/projects/hermes-tutorials    84 MB  247 commits
  /home/you/projects/my-app             32 MB   89 commits
  /home/you/.hermes/skills              18 MB   56 commits
  /home/you/.hermes/plugins              8 MB   23 commits

Each project shows the disk space consumed and how many checkpoint “commits” exist. You can browse the checkpoint store directly:

ls ~/.hermes/checkpoints/store/

Rolling Back a File

Because checkpoints use git under the hood, you can inspect and revert with standard git commands:

cd ~/.hermes/checkpoints/store/your-project.git
git log --oneline -5
git show HEAD:path/to/file
git checkout HEAD~1 -- path/to/file

Or simply re-run hermes on the working directory — Hermes can restore individual files from its checkpoint store on request via the /rollback slash command during an active session.

Pruning Old Checkpoints

Checkpoints accumulate over time. When disk is tight, prune orphan data:

hermes checkpoints prune

This deletes checkpoints for projects that no longer exist on the filesystem, and garbage-collects unreachable objects in the remaining repos.

If you need to reclaim all checkpoint disk space (and you have recent backups):

hermes checkpoints clear

This wipes the entire checkpoint base. All rollback history is gone — restore from a backup first if you might need it later.

Practical Workflow: Automated Daily Backup

Combine hermes cron create with hermes backup --quick for zero-touch daily snapshots. Create a wrapper script:

# ~/.hermes/scripts/daily-snapshot.sh
#!/usr/bin/env bash
set -euo pipefail
LABEL="daily-$(date +%Y%m%d)"
hermes backup --quick --label "$LABEL"
echo "Snapshot $LABEL created"

Make it executable:

chmod +x ~/.hermes/scripts/daily-snapshot.sh

Then schedule it:

hermes cron create "0 3 * * *" \
  --name "Daily Backup" \
  --script daily-snapshot.sh \
  --deliver local \
  --no-agent

This runs every day at 3 AM, creates a labeled state snapshot, writes the confirmation to a local delivery file. No LLM cost — --no-agent skips the agent entirely.

Full Backup to External Storage

For off-machine protection, pair the snapshot with an rsync or rclone command:

# ~/.hermes/scripts/offsite-snapshot.sh
#!/usr/bin/env bash
set -euo pipefail
LABEL="offsite-$(date +%Y%m%d-%H%M)"
hermes backup --quick --label "$LABEL"
rclone copy ~/.hermes/state-snapshots/"$(date +%Y%m%d)"-*/ \
  my-backup-bucket:hermes-snapshots/ --progress
echo "Offsite snapshot $LABEL complete"

Disaster Recovery Walkthrough

Here’s the complete drill for a hypothetical disaster — your config.yaml is corrupted after a failed hermes config set:

1. Detect the Problem

hermes doctor

Hermes reports:

✗ config.yaml: YAML parse error at line 47 (mapping values are not allowed here)
✗ state.db: File size 0 bytes (corrupt)

2. Find Your Most Recent Snapshot

ls -lt ~/.hermes/state-snapshots/ | head -5

20260706-171230-pre-tutorial
20260608-070336-pre-update
20260521-220825-pre-update
20260515-201047-pre-update

3. Restore the Broken Files

# Stop gateway to prevent partial writes
hermes gateway stop

# Restore from the snapshot
cp ~/.hermes/state-snapshots/20260706-171230-pre-tutorial/config.yaml ~/.hermes/config.yaml
cp ~/.hermes/state-snapshots/20260706-171230-pre-tutorial/state.db ~/.hermes/state.db

# Verify
hermes doctor

Output:

✓ config.yaml: valid
✓ state.db: 38 MB, integrity check passed
✓ gateway: stopped (will start on next run)
✓ All systems nominal

4. Resume Operations

hermes gateway start
hermes --continue

You’re back to where you were before the corruption. The snapshots cost a few kilobytes of disk each (except state.db) and saved you from reconfiguring from scratch.

5. Clean Up the Corrupted Snapshot (Optional)

rm -rf ~/.hermes/state-snapshots/20260706-171230-pre-tutorial

Keep the ones you trust and delete the rest. Use --label to make selection obvious.

Checkpoint Internals (For the Curious)

The checkpoint store is a bare git repository per project. Hermes runs git add -A && git commit -m "checkpoint" before every supported tool call. This means you can interact with it using standard porcelain:

cd ~/.hermes/checkpoints/store/hermes-tutorials.git
git log --oneline --all | head -10
git diff HEAD~1 -- src/content/blog/my-post.mdx

The shadow repo doesn’t interfere with your project’s own git history — it’s completely separate and tracks every write, not just your manual commits.

What Triggers a Checkpoint

Hermes Tool	Checkpoint Taken
`write_file`	Always — before writing new content
`patch`	Always — before applying the edit
`terminal`	When the command alters files in the workdir
`read_file`	Never (read-only)
`web_search`	Never
`web_extract`	Never

Configuration Reference

You can configure checkpoint behavior in ~/.hermes/config.yaml:

checkpoints:
  enabled: true              # Set false to disable checkpoints entirely
  store_path: ~/.hermes/checkpoints  # Where checkpoints live
  max_store_size_mb: 2000    # Soft limit (2 GB) — prune warns when exceeded
  projects:
    exclude:                 # Directories to never checkpoint
      - /tmp
      - /var/tmp
      - node_modules
    include:                 # Override — only checkpoint these dirs
      # - /home/you/critical-project

And for backup:

backup:
  default_output: ~/hermes-backups/
  quick_labels: true
  auto_clean: 30            # Delete snapshots older than N days (0 = keep forever)

These settings let you tune the balance between safety and disk usage. On a laptop with a 512 GB SSD, 2 GB for checkpoints is negligible. On a Raspberry Pi running Hermes headless, you might want to tighten it.

Summary

hermes backup --quick is your first line of defense — 8 critical files, under 1 second, labeled for easy identification
hermes backup (full) creates a complete zip archive of everything under ~/.hermes/
hermes checkpoints tracks every file operation automatically via shadow git repos
Combine hermes cron create + --no-agent for automated daily snapshots at zero LLM cost
Always run hermes doctor after a restore to verify integrity
Three layers means you’re protected at the config, session, and file-operation level — losing everything requires simultaneous failure of all three

Configuration Deep Dive — Every config.yaml section explained
How to Manage Multiple Profiles and Cron Jobs — Profiles, cron, and automation patterns
CLI Mastery: Commands, Sessions, and Slash Commands — Full Hermes CLI reference
Build Log: Creating a Hermes Agent Cron Pipeline — Script-only cron for health monitoring
Hermes Agent Doctor & Troubleshooting — Self-diagnostics and common fixes
ToolBrain — Tool reviews, LLM comparisons, and AI workflow guides
NoCode Insider — AI workflow automation with no-code tools and agents
NiteAgent — AI agent development, frameworks, and production patterns

Cross-links automatically generated from Hermes Tutorials.

Hermes Agent Backup, Restore & Safety Net: Never Lose Your Config

Key Takeaways

Why You Need a Safety Net

Layer 1: State Snapshots with hermes backup --quick

Creating a Snapshot

Restoring from a Snapshot

Layer 2: Full Backup Archives

What the Full Archive Contains

Layer 3: Automatic File Checkpoints

Checking Checkpoint Status

Rolling Back a File

Pruning Old Checkpoints

Practical Workflow: Automated Daily Backup

Full Backup to External Storage

Disaster Recovery Walkthrough

1. Detect the Problem

2. Find Your Most Recent Snapshot

3. Restore the Broken Files

4. Resume Operations

5. Clean Up the Corrupted Snapshot (Optional)

Checkpoint Internals (For the Curious)

What Triggers a Checkpoint

Configuration Reference

Summary

Related Reads

Layer 1: State Snapshots with `hermes backup --quick`