Chapter 9: Security & Best Practices

The cuttlefish is very capable, but with great power comes great responsibility. This chapter covers Hermes Agent's seven-layer security defense and best practices for daily use.

Seven-Layer Security Model

Hermes Agent employs a Defense-in-Depth architecture:

┌─────────────────────────────┐
│  Layer 1: Command Approval  │  ← Dangerous commands require human confirmation
├─────────────────────────────┤
│  Layer 2: User Authorization│  ← Gateway access control
├─────────────────────────────┤
│  Layer 3: Container Isolation│  ← Docker / Sandbox
├─────────────────────────────┤
│  Layer 4: Terminal Backend   │  ← Backend selection & permissions
├─────────────────────────────┤
│  Layer 5: Env Var Isolation  │  ← Secret management
├─────────────────────────────┤
│  Layer 6: Network Security   │  ← TLS / WebSocket
├─────────────────────────────┤
│  Layer 7: Data Storage       │  ← Local encryption, file permissions
└─────────────────────────────┘

---

Command Approval System

Before executing terminal commands, the Agent checks whether they match dangerous patterns. If they do, the user must explicitly approve.

Approval Mode

# ~/.hermes/config.yaml
approvals:
  mode: default    # default | off

Mode	Behavior
default	Dangerous commands trigger an approval prompt
off	Disable all safety prompts (only for trusted environments like CI/CD, containers)

YOLO Mode

Temporarily skip all dangerous command approvals:

/yolo          # Toggle on/off

Or enable at startup:

hermes --yolo

Danger

YOLO mode disables all command safety checks. Only use it in fully trusted environments (e.g., one-time containers, test environments).

Approval Timeout

# ~/.hermes/config.yaml
approvals:
  timeout: 300    # Default 300 seconds; auto-reject on timeout (fail-closed)

Approval Flow

CLI mode: Inline prompt, type y/n

Gateway/chat mode: Sends an interactive card with buttons for the user to click:

• Allow Once — Allow this time only
• Session — Allow for this session
• Always — Permanently add to allowlist
• Deny — Reject

Permanent Allowlist

# ~/.hermes/config.yaml
approvals:
  allowlist:
    - "git push"
    - "npm test"

Commands matching allowlist patterns won't trigger approval.

---

User Authorization (Gateway)

Authorization Check Order

1. Check GATEWAY_ALLOW_ALL_USERS
   ↓ If false
2. Check GATEWAY_ALLOWED_USERS (user ID list)
   ↓ If no match
3. Check DM pairing records
   ↓ If not paired
4. Deny access

Platform-Level Allowlist

You can set different allowed users for different platforms:

# Global
GATEWAY_ALLOWED_USERS=user_a,user_b

# Platform-specific
TELEGRAM_ALLOWED_USERS=123456789
DISCORD_ALLOWED_USERS=987654321

DM Pairing System

The most recommended approach. New users receive a pairing code when they DM the bot; you confirm in the CLI:

hermes gateway pair <code>

Pairing code features: cryptographic random generation, 1-hour validity, rate-limited.

---

Container Isolation

When running in Docker, Singularity, Modal, or other container backends, dangerous command checks are automatically skipped — the container itself is the security boundary. Destructive commands inside the container won't affect the host machine.

Docker Security Configuration

hermes --backend docker

Docker runtime security flags:

• Read-only root filesystem
• No privilege escalation
• Resource limits (CPU, memory)

Resource Limits

# ~/.hermes/config.yaml
container:
  memory: 2g
  cpus: 2

---

Environment Variable Security

Secret Management Principles

1. Never enter secrets in chat — Use hermes setup or edit ~/.hermes/.env
2. Don't commit .env to Git — Ensure .gitignore includes .env
3. Apply least privilege — Only give API keys the permissions they need

Environment Variable Passthrough

Environment variables declared by Skills are automatically passed to the execute_code and terminal sandboxes. Non-Skill environment variables require explicit configuration:

# ~/.hermes/config.yaml
terminal:
  env_passthrough:
    - MY_CUSTOM_VAR

---

Best Practices Checklist

Installation Phase

• [ ] Use the latest version of Hermes Agent
• [ ] Install in an isolated directory, not mixed with other projects
• [ ] Ensure Python virtual environment isolation
• [ ] Verify hermes doctor output shows no errors

Configuration Phase

• [ ] Don't use GATEWAY_ALLOW_ALL_USERS=true (except for local testing)
• [ ] Configure GATEWAY_ALLOWED_USERS or enable DM pairing
• [ ] Store API keys in ~/.hermes/.env with file permissions set to 600
• [ ] Keep approval mode at default; don't set to off

Runtime Phase

• [ ] Update regularly: hermes update
• [ ] Periodically check hermes gateway status
• [ ] Review Cron task output logs
• [ ] Audit Skills automatically created by the Agent

Multi-User Environments

• [ ] Use a separate HERMES_HOME for each Agent instance
• [ ] Use different allowlists for different users
• [ ] Set approval timeouts for sensitive operations
• [ ] Regularly review command patterns in the allowlist

---

Common Security Issues

Scenario	Risk	Recommendation
Running Gateway on a public VPS	Anyone could reach your Bot	Configure allowlist + DM pairing
Using --yolo mode	Agent can execute arbitrary commands	Only use inside containers
API key leak	Others can use your quota	Rotate keys regularly, check usage
Multiple people sharing a Bot	One person can affect everyone's sessions	Use Profile isolation
Cron execution failure	Tasks fail silently	Check cron/output/ logs

Further Reading

• Official docs: Security
• Docker runtime: Hermes Agent Docker
• FAQ & troubleshooting: FAQ & Troubleshooting

---