hermes-backup

name	hermes-backup
description	Manage Hermes backup status, health checks, and operations via launchd + restic
triggers	["backup status","backup health","force backup","check backup","last backup","restic check","backup logs","restore snapshot"]

Hermes Backup

Hermes Agent backs up its config, skills, and dotfiles to S3-compatible storage (DigitalOcean Spaces) via restic. The backup runner is scheduled through macOS launchd — it runs even when Hermes is broken.

Quick Reference

Action	Command
Check status	cat ~/.hermes-backup/status/latest.json | jq .
Force backup	bash ~/.hermes-backup/bin/backup.sh --restore-check
View recent logs	ls -t ~/.hermes-backup/logs/| head -3
Run watchdog	bash ~/.hermes-backup/bin/watchdog.sh
Run maintenance	bash ~/.hermes-backup/bin/maintenance.sh
Check launchd	launchctl print gui/$(id -u)/com.xlyk.hermes-backup
List snapshots	source ~/.hermes-backup/config/restic.env && restic snapshots

Status File

~/.hermes-backup/status/latest.json contains the last backup result:

{
  "status": "ok",
  "stage": "backup+restore",
  "snapshot_id": "...",
  "restore_check": "ok",
  "last_success_at": "2026-05-21T14:46:50Z"
}

Fields:

• status: ok, running, failed, or degraded
• restore_check: ok or failed — validates data integrity
• last_success_at: ISO timestamp of last fully-verified backup

Schedule

• Daily backup: 3:00 AM via launchd (com.xlyk.hermes-backup)
• Weekly maintenance: Sunday 4:00 AM via launchd (com.xlyk.hermes-backup-maintenance)
• Health check: Every 2 hours via Hermes cron (watchdog, optional setup)

Restoring

Full restore instructions at: ~/.hermes-backup/restore-kit/README-RESTORE.md

Quick restore:

source ~/.hermes-backup/config/restic.env
restic restore latest --target /tmp/restore
# Config, skills, dotfiles land at /tmp/restore/Users/...
cp -r /tmp/restore/Users/$USER/.hermes/config.yaml ~/.hermes/

Configuration

Secrets live in ~/.hermes-backup/config/restic.env (chmod 600):

RESTIC_REPOSITORY=s3:https://sfo3.digitaloceanspaces.com/YOUR-BUCKET/PATH
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
RESTIC_PASSWORD=...

Backup Scope

Only what can't be re-created from a fresh Hermes clone:

• ~/.hermes/config.yaml and .env
• ~/.hermes/skills/ (custom skills)
• ~/.hermes/cron/ (schedule state)
• ~/.hermes/kanban.db (in-flight work)
• ~/.hermes/auth.json, honcho.json, state JSON files
• Dotfiles: .gitconfig, .zshrc, .zprofile
• ~/.config/tmux/
• ~/Library/LaunchAgents/
• Restore kit and backup state