安全设置

approvals:
  mode: manual    # manual | smart | off
  timeout: 60     # seconds to wait for user response (default: 60)

> /yolo
  ⚡ YOLO mode ON — all commands auto-approved. Use with caution.

> /yolo
  ⚠ YOLO mode OFF — dangerous commands will require approval.

approvals:
  timeout: 60  # seconds (default: 60)

  ⚠️  DANGEROUS COMMAND: recursive delete
      rm -rf /tmp/old-project

      [o]nce  |  [s]ession  |  [a]lways  |  [d]eny

      Choice [o/s/a/D]:

# Permanently allowed dangerous command patterns
command_allowlist:
  - rm
  - systemctl

# Platform-specific allowlists
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=111222333444555666
WHATSAPP_ALLOWED_USERS=15551234567
SLACK_ALLOWED_USERS=U01ABC123

# Cross-platform allowlist (checked for all platforms)
GATEWAY_ALLOWED_USERS=123456789

# Per-platform allow-all (use with caution)
DISCORD_ALLOW_ALL_USERS=true

# Global allow-all (use with extreme caution)
GATEWAY_ALLOW_ALL_USERS=true

No user allowlists configured. All unauthorized users will be denied.
Set GATEWAY_ALLOW_ALL_USERS=true in ~/.hermes/.env to allow open access,
or configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id).

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

# List pending and approved users
hermes pairing list

# Approve a pairing code
hermes pairing approve telegram ABC12DEF

# Revoke a user's access
hermes pairing revoke telegram 123456789

# Clear all pending codes
hermes pairing clear-pending

_SECURITY_ARGS = [
    "--cap-drop", "ALL",                          # Drop ALL Linux capabilities
    "--cap-add", "DAC_OVERRIDE",                  # Root can write to bind-mounted dirs
    "--cap-add", "CHOWN",                         # Package managers need file ownership
    "--cap-add", "FOWNER",                        # Package managers need file ownership
    "--security-opt", "no-new-privileges",         # Block privilege escalation
    "--pids-limit", "256",                         # Limit process count
    "--tmpfs", "/tmp:rw,nosuid,size=512m",         # Size-limited /tmp
    "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m",  # No-exec /var/tmp
    "--tmpfs", "/run:rw,noexec,nosuid,size=64m",   # No-exec /run
]

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_forward_env: []  # Explicit allowlist only; empty keeps secrets out of the container
  container_cpu: 1        # CPU cores
  container_memory: 5120  # MB (default 5GB)
  container_disk: 51200   # MB (default 50GB, requires overlay2 on XFS)
  container_persistent: true  # Persist filesystem across sessions

# In a skill's SKILL.md frontmatter
required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor

For env vars not declared by any skill, add them to terminal.env_passthrough in config.yaml:

terminal:
  env_passthrough:
    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

Credential File Passthrough (OAuth tokens, etc.) {#credential-file-passthrough}

Some skills need files (not just env vars) in the sandbox — for example, Google Workspace stores OAuth tokens as google_token.json under the active profile's HERMES_HOME. Skills declare these in frontmatter:

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token (created by setup script)
  - path: google_client_secret.json
    description: Google OAuth2 client credentials

When loaded, Hermes checks if these files exist in the active profile's HERMES_HOME and registers them for mounting:

• Docker: Read-only bind mounts (-v host:container:ro)
• Modal: Mounted at sandbox creation + synced before each command (handles mid-session OAuth setup)
• Local: No action needed (files already accessible)

You can also list credential files manually in config.yaml:

terminal:
  credential_files:
    - google_token.json
    - my_custom_oauth_token.json

Paths are relative to ~/.hermes/. Files are mounted to /root/.hermes/ inside the container.

What Each Sandbox Filters

Security Considerations

• The passthrough only affects vars you or your skills explicitly declare — the default security posture is unchanged for arbitrary LLM-generated code
• Credential files are mounted read-only into Docker containers
• Skills Guard scans skill content for suspicious env access patterns before installation
• Missing/unset vars are never registered (you can't leak what doesn't exist)
• Hermes infrastructure secrets (provider API keys, gateway tokens) should never be added to env_passthrough — they have dedicated mechanisms

MCP Credential Handling

MCP (Model Context Protocol) server subprocesses receive a filtered environment to prevent accidental credential leakage.

Safe Environment Variables

Only these variables are passed through from the host to MCP stdio subprocesses:

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR

Plus any XDG_* variables. All other environment variables (API keys, tokens, secrets) are stripped.

Variables explicitly defined in the MCP server's env config are passed through:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."  # Only this is passed

Credential Redaction

Error messages from MCP tools are sanitized before being returned to the LLM. The following patterns are replaced with [REDACTED]:

• GitHub PATs (ghp_...)
• OpenAI-style keys (sk-...)
• Bearer tokens
• token=, key=, API_KEY=, password=, secret= parameters

Website Access Policy

You can restrict which websites the agent can access through its web and browser tools. This is useful for preventing the agent from accessing internal services, admin panels, or other sensitive URLs.

# In ~/.hermes/config.yaml
security:
  website_blocklist:
    enabled: true
    domains:
      - "*.internal.company.com"
      - "admin.example.com"
    shared_files:
      - "/etc/hermes/blocked-sites.txt"

When a blocked URL is requested, the tool returns an error explaining the domain is blocked by policy. The blocklist is enforced across web_search, web_extract, browser_navigate, and all URL-capable tools.

See Website Blocklist in the configuration guide for full details.

SSRF Protection

All URL-capable tools (web search, web extract, vision, browser) validate URLs before fetching them to prevent Server-Side Request Forgery (SSRF) attacks. Blocked addresses include:

• Private networks (RFC 1918): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
• Loopback: 127.0.0.0/8, ::1
• Link-local: 169.254.0.0/16 (includes cloud metadata at 169.254.169.254)
• CGNAT / shared address space (RFC 6598): 100.64.0.0/10 (Tailscale, WireGuard VPNs)
• Cloud metadata hostnames: metadata.google.internal, metadata.goog
• Reserved, multicast, and unspecified addresses

SSRF protection is always active and cannot be disabled. DNS failures are treated as blocked (fail-closed). Redirect chains are re-validated at each hop to prevent redirect-based bypasses.

Tirith Pre-Exec Security Scanning

Hermes integrates tirith for content-level command scanning before execution. Tirith detects threats that pattern matching alone misses:

• Homograph URL spoofing (internationalized domain attacks)
• Pipe-to-interpreter patterns (curl | bash, wget | sh)
• Terminal injection attacks

Tirith auto-installs from GitHub releases on first use with SHA-256 checksum verification (and cosign provenance verification if cosign is available).

# In ~/.hermes/config.yaml
security:
  tirith_enabled: true       # Enable/disable tirith scanning (default: true)
  tirith_path: "tirith"      # Path to tirith binary (default: PATH lookup)
  tirith_timeout: 5          # Subprocess timeout in seconds
  tirith_fail_open: true     # Allow execution when tirith is unavailable (default: true)

When tirith_fail_open is true (default), commands proceed if tirith is not installed or times out. Set to false in high-security environments to block commands when tirith is unavailable.

Tirith's verdict integrates with the approval flow: safe commands pass through, while both suspicious and blocked commands trigger user approval with the full tirith findings (severity, title, description, safer alternatives). Users can approve or deny — the default choice is deny to keep unattended scenarios secure.

Context File Injection Protection

Context files (AGENTS.md, .cursorrules, SOUL.md) are scanned for prompt injection before being included in the system prompt. The scanner checks for:

• Instructions to ignore/disregard prior instructions
• Hidden HTML comments with suspicious keywords
• Attempts to read secrets (.env, credentials, .netrc)
• Credential exfiltration via curl
• Invisible Unicode characters (zero-width spaces, bidirectional overrides)

Blocked files show a warning:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

Best Practices for Production Deployment

Gateway Deployment Checklist

1. Set explicit allowlists — never use GATEWAY_ALLOW_ALL_USERS=true in production
2. Use container backend — set terminal.backend: docker in config.yaml
3. Restrict resource limits — set appropriate CPU, memory, and disk limits
4. Store secrets securely — keep API keys in ~/.hermes/.env with proper file permissions
5. Enable DM pairing — use pairing codes instead of hardcoding user IDs when possible
6. Review command allowlist — periodically audit command_allowlist in config.yaml
7. Set MESSAGING_CWD — don't let the agent operate from sensitive directories
8. Run as non-root — never run the gateway as root
9. Monitor logs — check ~/.hermes/logs/ for unauthorized access attempts
10. Keep updated — run hermes update regularly for security patches

Securing API Keys

# Set proper permissions on the .env file
chmod 600 ~/.hermes/.env

# Keep separate keys for different services
# Never commit .env files to version control

Network Isolation

For maximum security, run the gateway on a separate machine or VM:

terminal:
  backend: ssh
  ssh_host: "agent-worker.local"
  ssh_user: "hermes"
  ssh_key: "~/.ssh/hermes_agent_key"

This keeps the gateway's messaging connections separate from the agent's command execution.