Security, Reliability, and Operations

Every chapter before this one focused on building something. This one focuses on keeping what you built running — and making sure the wrong things do not happen along the way.

Hermes runs on your machine, with access to your files, your API keys, and your shell. That power is what makes it useful. It is also what makes security and reliability non-negotiable. An agent that can run commands on your server can also run the wrong commands. A cron job that fails silently can leave you thinking work happened when it did not.

Defense in depth

Seven layers between your agent and your system

Hermes uses a defense-in-depth model — no single layer catches everything, and a failure in one layer is caught by the next. Layers 2–7 are active by default. Layer 1 (user authorization) requires allowlist setup covered in Chapter 5.

1. User authorization — allowlists and DM pairing reject unauthorized messages at the gateway
2. Dangerous command approval — destructive operations require explicit permission before running
3. Container isolation — Docker, Singularity, and Modal sandboxes prevent host filesystem access
4. MCP credential filtering — API keys stay in the main process, not handed to every subprocess
5. Context file scanning — flags prompt injection attempts in shared context files before the agent acts
6. Cross-session isolation — sessions cannot access each other's data or state
7. Input sanitization — working directory and parameters validated against allowlists to prevent shell injection

Protecting credentials

Where your secrets live and how they stay safe

Hermes stores API keys in ~/.hermes/.env, not in config.yaml. Config contains preferences (model, toolsets, approval mode) and may be shared or exported; .env contains secrets and must never be committed, shared, or included in a profile export. Secret redaction is on by default and cannot be disabled at runtime — it is frozen at import time to prevent an agent from turning it off mid-session. Hermes scans logs and output for API key patterns (vendor prefixes like sk-, sk-ant-, sensitive query parameter names, and long alphanumeric strings), then masks them — short tokens are fully replaced, longer ones preserve the first six and last four characters so you can identify which key was used. The full pattern list lives in agent/redact.py.

Human in the loop

When the agent asks permission before acting

Before Hermes executes a command, it checks against a curated list of dangerous patterns — file deletion, writing to sensitive paths, package installation, network operations piped to shell, privilege escalation. When a match is found, the agent pauses and asks for permission. Chapter 7 covered how this works in the agent loop; here is the configuration:

Three approval modes (Ch7): manual (default, safest — every dangerous command requires explicit approval), smart (auxiliary LLM assesses risk — low-risk auto-approved, dangerous auto-denied, uncertain escalated to you), off (disposable environments only — every command executes immediately). YOLO mode toggles per-session with /yolo and bypasses all approval prompts for that session only. The hardline blocklist is always on — even in YOLO mode, even with approvals off, commands like rm -rf /, fork bombs, and raw block device overwrites are blocked unconditionally. There is no override flag.

Resilience

What happens when your model provider goes down

Your agent depends on a model provider to think. If that provider goes down, your agent stops. Hermes provides three layers of resilience: credential pools rotate across multiple API keys for the same provider so a rate-limited key passes to the next; primary model fallback automatically switches to a different provider and model on the same turn, then restores the primary for the next turn; auxiliary task fallback gives side tasks like vision and context compression independent provider resolution so they degrade gracefully even when the main provider is down. Always configure at least one fallback — a single rate limit event can halt an entire cron pipeline without one.

hermes fallback

When things break

Three things that break

Recovery

What to back up and how to do it

Everything that matters lives in ~/.hermes. Config, profiles, memory, skills, cron jobs, API keys — lose this directory and you lose your entire setup.

hermes backup

Produces a timestamped zip in your home directory. Excludes the hermes-agent code repository, bytecode caches, and transient runtime files. Includes everything else: config, profiles, memory, skills, cron jobs, session databases, and your .env file with API keys.

hermes backup --output /path/to/backup.zip

hermes import /path/to/backup.zip

Import overlays the backup onto your current ~/.hermes directory — existing files are overwritten, but files not in the backup are preserved.

Maintenance

How to update without breaking your setup

Hermes updates frequently. The update command handles the git pull, dependency reinstall, and gateway restart. Active sessions are preserved across the restart. Before you update, follow this sequence:

hermes update

1. Back up first — run hermes backup. Takes seconds, saves hours if the update introduces a regression.
2. Check what changed — read the release notes for breaking changes to config format, new required fields, or deprecated features.
3. Run the update — hermes update handles git pull, dependency reinstall, and gateway restart.
4. Run the doctor — hermes doctor catches config problems introduced by the update: missing fields, changed defaults, failed migrations.
5. Verify your agents — test one manual session with each active profile. Confirm model connectivity, tools, memory, cron jobs, and gateway.

hermes doctor

The doctor checks Python/Node availability, API key configuration, model provider connectivity, toolset loading, profile integrity, and gateway status. Run it after any change that might affect your setup.

Running reliably

Six habits that prevent most problems

Security features and backup commands are necessary but not sufficient. The difference between a setup that runs for months and one that breaks weekly is operational habits.

1. Back up before every change — before updates, config edits, new profiles, or cron schedule changes. Seconds to run, minutes to restore, hours to rebuild without it.
2. Run the doctor after every update — catches config problems before they become silent failures. Make it a reflex: update, then doctor.
3. Always configure a fallback provider — model providers go down, rate limits happen, keys expire. One fallback keeps your pipeline running.
4. Deliver cron output to a messaging channel — silent failures are the most dangerous kind. Configure deliver on every job so errors arrive immediately.
5. Keep approvals on manual for production — smart mode is convenient for development. Manual mode is the right choice for profiles with access to sensitive systems.
6. Review memory and skills periodically — memory grows, skills accumulate. Outdated facts degrade agent quality. Review monthly, delete contradictions, keep files compact.

Final note

Security is a practice, not a feature

Hermes provides the mechanisms — approvals, redaction, fallbacks, backups, isolation. They work automatically when configured. But no mechanism replaces judgment. You decide which approval mode to use, whether to configure fallbacks, whether to back up before an update. The six habits in this chapter are how you use those mechanisms consistently.

The reward is a setup that runs reliably for months. The cost of skipping it is unpredictable failures at the worst possible time — a cron job that silently stops, an API key that leaks into a log, a config change that disables your approval mode without you noticing. These are not theoretical risks. They are the normal failure modes of any long-running system. The defenses in this chapter are how you avoid them.