2026 Hermes Agent Long-Term Maintenance Best Practices: Updates, Logs, Backup & Restart Recovery Playbook

2. Pain points unpacked

1. Constraint: unattended ≠ maintenance-free. macOS, Homebrew/pip, and Hermes release cycles do not align; running hermes update without acceptance leaves gateway or cron in a half-upgraded state.
2. Hidden cost: PATH and launchd env mismatch. git and node work in your interactive shell, but the launchd-managed gateway cannot find binaries—task logs show only vague tool errors.
3. Stability and audit: no backup means no rollback point. Config lives across ~/.hermes/config.yaml, .env, skills, and session DB; keys stored only in chat break the whole chain on rotation.

3. What to back up (pre-update checklist)

Default data directory is HERMES_HOME (usually ~/.hermes). Confirm paths with hermes config path and hermes config env-path; each profile has its own home.

Recommended commands: daily quick snapshot hermes backup --quick --label "pre-upgrade"; before major changes hermes backup -o ~/hermes-backups/$(date +%F).zip. Restore with hermes import. Note: official backup does not include the Hermes code repo itself (git vs pip rollback differs).

4. Upgrade without breaking the environment: cadence, matrices, and seven-step runbook

4.1 Update cadence: macOS, dependencies, and Hermes

Do not assume auto-update is safe. Whether git pull or pip install --upgrade, follow backup → update → minimal task acceptance → keep rollback zip. Set update.backup: true in config.yaml, or run hermes update --backup once.

4.2 Seven-step upgrade and acceptance runbook

1. Record baseline: write hermes version, hermes dump, and hermes gateway status to your change ticket.
2. Backup: hermes backup --quick --label "pre-$(date +%Y%m%d)" or a full zip.
3. Pre-check: hermes update --check; hermes doctor --fix for auto-fixable items.
4. Run update: during the maintenance window hermes update --backup (git install pulls code and reinstalls deps; pip install upgrades from PyPI).
5. Minimal acceptance: hermes chat -q "reply OK"; if using a gateway, send a real message from Telegram/Discord.
6. Restart test: hermes gateway restart; optionally reboot Mac to verify launchd auto-start.
7. Rollback on failure: hermes import <backup.zip>, or restore config/.env then hermes gateway restart; downgrade pip/git per install method.

5. Logs and health checks

5.1 Log locations and common commands

Default directory: ~/.hermes/logs/ (non-default profiles use the matching HERMES_HOME/logs/).

• agent.log — API calls, tool dispatch, session lifecycle (INFO+)
• errors.log — WARNING and above; first stop for troubleshooting
• gateway.log — messaging platform connections and webhooks

hermes logs list
hermes logs errors --since 30m -n 100
hermes logs gateway -f
hermes logs --level ERROR --since 2h --component tools

The framework rotates agent.log (e.g. to agent.log.1). Archive *.log.* older than 30 days monthly to cold storage; cap checkpoint shadow repos with hermes checkpoints prune --max-size-mb 500.

5.2 Health check thresholds (suggested)

Daily checks can be scripted: hermes doctor + hermes logs errors --since 24h + df -h. For external alerting, pipe ERROR lines into your log pipeline (JSONL sidecar or hermes debug share --local for manual upload).

6. Reboot, network loss, sleep, and recovery drills

After Mac sleep/wake, check hermes gateway status first; if not running, hermes gateway start (launchd install scenario). After network recovery, confirm gateway.log shows reconnect.

Quarterly drill (add to calendar):

1. Full hermes backup to off-site directory
2. Reboot Mac → wait 3 minutes → hermes status --deep
3. Send test message from messaging platform + hermes cron tick (if cron jobs exist)
4. Record RTO: time from boot to gateway available (target < 5 minutes, varies by model and login items)

For remote physical Macs (e.g. ZoneMac nodes), also verify: SSH reachable, same user as launchd, PATH includes git/node—same root cause as PATH issues in OpenClaw Gateway launchd troubleshooting.

7. Secrets and permissions review

• API keys (OpenRouter, Anthropic, etc.): rotate every 90 days; use hermes auth add/remove, never plaintext in skills.
• OAuth (Codex, Anthropic, Copilot): hermes auth status <provider>; re-OAuth on expiry, not .env edits.
• Tool permissions: monthly hermes tools list; disable unused terminal/browser/MCP.
• Pairing and webhooks: hermes pairing list; clean unused subscriptions.

8. Maintenance calendar (paste into Reminders)

Quotable parameters (for your internal wiki)

• Default log directory: ~/.hermes/logs/, rotated files agent.log.1+
• Quick backup typical size: a few MB to hundreds of MB (depends on sessions and skills); full backup—reserve disk ≥ 2× HERMES_HOME
• Production gateway health poll: check status every 30–60s; < 5 ERROR lines per hour as a starting threshold
• Checkpoint repo default cap: prune --max-size-mb 500 (adjust for disk)

FAQ

Q: How does rollback differ for brew vs pip installs?

A: pip can reinstall the previous wheel; git install can git checkout a known commit and reinstall deps. Either way, user data rollback is via hermes import—do not downgrade the binary without restoring config.

Q: How do I back up multiple profiles?

A: Run hermes -p <name> backup for each profile HERMES_HOME; after update with multiple gateways, use hermes gateway restart --all.