Hermes Agent

Hermes Agent リファレンス

Hermes Agent — Nous Research が開発したオープンソース AI CLI エージェント。 マルチ LLM プロバイダー対応、メッセージングプラットフォーム統合、MCP 連携、音声モード、スキルシステムを備える。 CLI 操作・設定カスタマイズ・機能活用・デプロイ時に参照する。

ディレクトリ構造

.claude/skills/hermes-agent/
├── SKILL.md                                    ← このファイル（エントリーポイント）
└── references/
    ├── getting-started/README.md               ← Getting Started 索引（3ページ）
    ├── cli/README.md                           ← CLI 索引（2ページ）
    ├── configuration/README.md                 ← Configuration 索引（1ページ）
    ├── features/README.md                      ← Features 索引（7ページ）
    ├── messaging/README.md                     ← Messaging Gateway 索引（1ページ）
    ├── security/README.md                      ← Security 索引（1ページ）
    ├── guides/README.md                        ← Guides 索引（3ページ）
    ├── architecture/README.md                  ← Architecture 索引（1ページ）
    └── reference/README.md                     ← Reference 索引（2ページ）

探索手順

1. ユーザーのタスクに最も関連するカテゴリを特定する 2. そのカテゴリの README.md を読む 3. README.md 内の一覧から必要な個別ファイルを選んで読む 4. 必要に応じて関連ページのリンクを辿る

カテゴリ → README.md マッピング

Architecture Overview

High-level structure and major subsystems of the Hermes Agent framework.

High-Level Structure

Major Subsystems

Agent Loop

The synchronous orchestration engine. Responsibilities:

• Provider / API-mode selection
• Prompt construction
• Tool execution
• Retries and fallback
• Callbacks
• Context compression
• Session persistence

Prompt System

Distributed across three modules:

• Prompt-building logic
• Context compression
• Prompt caching

Design goal: stability and token efficiency across long sessions.

Provider Runtime

A shared resolver handles model provider selection for all entry points (CLI, gateway, cron, ACP), ensuring consistent API routing regardless of how the agent is invoked.

Tooling Runtime

Coordinates:

• Tool registry
• Toolsets
• Terminal backends
• Process manager
• Dispatch rules

Provides a unified tool-execution surface for all subsystems.

Session Persistence

SQLite stores historical session state. Key property: lineage is preserved across compression splits, so long-running sessions remain coherent.

Messaging Gateway

A long-running layer that manages:

• Platform adapters
• Session routing and pairing
• Message delivery
• Cron ticking

ACP Integration

Exposes the agent as an editor-native agent over stdio / JSON-RPC, enabling IDE integration via the Agent Communication Protocol.

RL & Environments

Full environment framework supporting:

• Agent evaluation
• Reinforcement learning integration
• SFT (supervised fine-tuning) data generation

Design Principles

• Prompt stability — prompt-building logic is isolated to prevent regressions.
• Observable and interruptible tool execution — tool dispatch is traceable and can be interrupted.
• Persistent sessions — SQLite-backed state supports long-running operations across compression boundaries.
• Shared agent core across frontends — CLI, gateway, ACP, and cron all drive the same AIAgent engine.
• Loose coupling for optional subsystems — gateway, cron, and RL layers are independent and additive.

Related

• README

Architecture

CLI Commands Reference

Complete reference for all hermes CLI commands, subcommands, options, and flags.

Signature / Usage

hermes [global-options] <command> [subcommand/options]

Global Options

Top-Level Commands

---

hermes chat

hermes chat [options]

`--provider` values: auto openrouter nous openai-codex copilot-acp copilot anthropic huggingface zai kimi-coding minimax minimax-cn deepseek ai-gateway opencode-zen opencode-go kilocode alibaba

---

hermes model

Interactive provider and model selection interface. Enables provider switching, OAuth login, model browsing, and custom endpoint configuration.

In-session `/model` slash command:

---

hermes gateway

hermes gateway <subcommand>

---

hermes setup

hermes setup [model|terminal|gateway|tools|agent] [--non-interactive] [--reset]

---

hermes whatsapp

hermes whatsapp

Initiates WhatsApp pairing/setup flow including mode selection and QR-code pairing.

---

hermes login / hermes logout

hermes login [--provider nous|openai-codex] [--portal-url ...] [--inference-url ...]
hermes logout [--provider nous|openai-codex]

Supported methods: Nous Portal OAuth/device flow, OpenAI Codex OAuth/device flow.

---

hermes auth

hermes auth [subcommand]

Manages credential rotation pools and key lifecycle.

---

hermes status

hermes status [--all] [--deep]

---

hermes cron

hermes cron <list|create|edit|pause|resume|run|remove|status|tick>

edit supports: --clear-skills, --add-skill, --remove-skill

---

hermes webhook

hermes webhook <subscribe|list|remove|test>

Manages event-driven subscriptions (requires webhook platform enabled).

hermes webhook subscribe

hermes webhook subscribe <name> [options]

---

hermes doctor

hermes doctor [--fix]

---

hermes config

hermes config <subcommand>

---

hermes pairing

hermes pairing <list|approve|revoke|clear-pending>

---

hermes skills

hermes skills <subcommand>

---

hermes honcho

hermes honcho [--target-profile NAME] <subcommand>

Manages Honcho cross-session memory integration.

---

hermes memory

hermes memory <subcommand>

External memory provider management.

Supported providers: honcho openviking mem0 hindsight holographic retaindb byterover

---

hermes acp

hermes acp

Launches Hermes as an ACP (Agent Client Protocol) stdio server.

# Alternative entrypoints
hermes-acp
python -m acp_adapter

# Installation
pip install -e '.[acp]'

---

hermes mcp

hermes mcp <subcommand>

MCP (Model Context Protocol) server management and operation.

---

hermes plugins

hermes plugins [subcommand]

---

hermes tools

hermes tools [--summary]

Without a flag, launches the interactive per-platform configuration UI.

---

hermes sessions

hermes sessions <subcommand>

---

hermes insights

hermes insights [--days N] [--source platform]

---

hermes claw

hermes claw migrate [options]

OpenClaw-to-Hermes migration utility. Reads from ~/.openclaw, writes to ~/.hermes.

Covers 30+ configuration categories including persona, memory, skills, providers, messaging, agent behavior, MCP servers, TTS, and API key sources.

---

hermes profile

hermes profile <subcommand>

Multi-instance profile administration.

---

hermes completion

hermes completion [bash|zsh]

Outputs shell completion script to stdout.

---

Maintenance Commands

Related

• CLI Interface

CLI Interface

Overview of the Hermes Agent interactive CLI — startup modes, status bar, key bindings, slash commands, session management, context compression, and background sessions.

Signature / Usage

# Interactive mode (default)
hermes

# Single query (non-interactive)
hermes chat -q "Hello"

# Specific model
hermes chat --model "anthropic/claude-sonnet-4"

# Provider selection
hermes chat --provider nous
hermes chat --provider openrouter

# Enable toolsets
hermes chat --toolsets "web,terminal,skills"

# Preload skills
hermes -s hermes-agent-dev,github-auth

# Resume most recent session
hermes --continue
hermes -c

# Resume specific session
hermes --resume <session_id>
hermes --resume "refactoring auth"

# Isolated git worktree
hermes -w

# Verbose / debug output
hermes chat --verbose

Status Bar

The persistent status bar is displayed above the input area and updates in real time.

The layout adapts to terminal width: full → compact → minimal.

Context color thresholds:

Key Bindings

Slash Commands

Type / to open the autocomplete dropdown. Commands are case-insensitive.

Installed skills automatically register as additional slash commands.

Quick Commands

Custom shell commands that execute immediately without invoking the LLM. Defined in configuration:

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=utilization.gpu,memory.used

Session Management

Resuming Sessions

hermes --continue              # Most recent CLI session
hermes -c                      # Short form
hermes --resume <session_id>   # Specific session by ID
hermes --resume "auth fix"     # Session by title
hermes sessions list           # Browse past sessions
hermes sessions rename <id> <title>

Resuming restores full conversation history (messages, tool calls) from SQLite.

Session Storage

Sessions are stored in ~/.hermes/state.db (SQLite). The database holds session metadata, message history, lineage tracking, and full-text search indexes.

Context Compression

Long conversations are automatically summarized when approaching the context limit. Configuration:

compression:
  enabled: true
  threshold: 0.50
  summary_model: "google/gemini-3-flash-preview"

The first 3 turns and last 4 turns are preserved; middle content is summarized.

Background Sessions

Run isolated prompts as separate daemon threads without blocking the foreground session.

/background Analyze the logs in /var/log and summarize any errors from today

Input and Interruption

Multi-line input:

• Alt+Enter / Ctrl+J — insert newline
• End a line with \ to continue on the next line

Interrupting the agent:

• Type a new message and press Enter during processing
• Ctrl+C — interrupt the current operation
• Multiple messages sent during interrupt are combined into one prompt

The display.busy_input_mode config controls interrupt behavior:

Notes

• The banner shown at startup displays model, terminal backend, working directory, available tools, and installed skills.
• display.tool_preview_length controls truncation length for tool previews in the feed (default: 0 = no limit).
• Personalities (tone presets: helpful, concise, technical, creative, teacher, kawaii, pirate, etc.) can be selected or custom-defined in configuration.
• --quiet / -Q suppresses UI elements; --verbose enables debug output.

Related

• CLI Commands Reference

CLI

Configuration

Hermes agent configuration reference. Settings are stored in ~/.hermes/ and can be managed via the hermes config commands.

Directory Structure

~/.hermes/
  config.yaml      # Main settings (model, terminal, TTS, compression)
  .env             # API keys and secrets
  auth.json        # OAuth provider credentials
  SOUL.md          # Primary agent identity
  memories/        # Persistent memory files
  skills/          # Agent-created skills
  cron/            # Scheduled jobs
  sessions/        # Gateway sessions
  logs/            # Error and gateway logs

Configuration Management Commands

hermes config           # View current configuration
hermes config edit      # Open config.yaml in editor
hermes config set KEY VAL  # Set a specific value
hermes config check     # Verify configuration after updates
hermes config migrate   # Add missing options with defaults

Configuration Precedence

Highest to lowest priority:

1. CLI arguments (per-invocation overrides) 2. ~/.hermes/config.yaml (primary non-secret settings) 3. ~/.hermes/.env (secrets and fallback env vars) 4. Built-in defaults

Environment Variable Substitution

Reference environment variables in config.yaml using ${VAR_NAME} syntax:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
delegation:
  api_key: ${DELEGATION_KEY}

• Multiple references work in single values: url: "${HOST}:${PORT}"
• Undefined variables remain verbatim as ${UNDEFINED_VAR}
• Only ${VAR} syntax is supported — bare $VAR is not expanded

Terminal Backend Configuration

Local (default)

No isolation. Commands run directly on the host machine. No additional configuration required.

terminal:
  backend: local

Docker

Containerized execution with security hardening.

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # Mount launch dir to /workspace
  docker_forward_env:                   # Env vars to forward into container
    - "GITHUB_TOKEN"
  docker_volumes:                       # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"        # :ro for read-only
  container_cpu: 1                      # CPU cores (0 = unlimited)
  container_memory: 5120               # MB (0 = unlimited)
  container_disk: 51200                # MB (requires overlay2 on XFS+pquota)
  container_persistent: true           # Persist /workspace and /root across sessions

Security hardening applied automatically: --cap-drop ALL with only DAC_OVERRIDE, CHOWN, FOWNER re-added; --security-opt no-new-privileges; --pids-limit 256; sized tmpfs mounts.

SSH

Remote execution via SSH.

terminal:
  backend: ssh
  persistent_shell: true  # default: true for SSH

Required environment variables:

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

Optional:

TERMINAL_SSH_PORT=22                    # SSH port (default: 22)
TERMINAL_SSH_KEY=/path/to/private/key  # SSH private key path
TERMINAL_SSH_PERSISTENT=true            # Override persistent shell for SSH

Uses ControlMaster for connection reuse with 5-minute idle keepalive. Connects with BatchMode=yes and StrictHostKeyChecking=accept-new.

Modal

Cloud sandbox execution.

terminal:
  backend: modal
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120   # MB
  container_disk: 51200    # MB
  container_persistent: true  # Snapshot/restore filesystem

Required: MODAL_TOKEN_ID + MODAL_TOKEN_SECRET, or ~/.modal.toml. When container_persistent is enabled, the sandbox filesystem is snapshotted on cleanup and restored on next session. Snapshots tracked in ~/.hermes/modal_snapshots.json.

Daytona

Managed workspace execution.

terminal:
  backend: daytona
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120   # MB, converted to GiB
  container_disk: 10240    # MB, max 10 GiB enforced
  container_persistent: true  # Stop/resume instead of delete

Required: DAYTONA_API_KEY. Sandboxes follow naming pattern hermes-{task_id}. Disk requests above 10 GiB are capped with a warning.

Singularity / Apptainer

HPC-friendly containerization.

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120   # MB
  container_persistent: true  # Writable overlay persists

Required: apptainer or singularity binary in $PATH.

Scratch directory resolution order: 1. TERMINAL_SCRATCH_DIR 2. TERMINAL_SANDBOX_DIR/singularity 3. /scratch/$USER/hermes-agent 4. ~/.hermes/sandboxes/singularity

Full namespace isolation with --containall --no-home.

Persistent Shell

terminal:
  persistent_shell: true   # default: true for SSH, false for local

What persists across commands: working directory (cd sticks), exported env vars, shell variables.

Environment variable overrides (highest precedence):

• TERMINAL_SSH_PERSISTENT — controls SSH backend
• TERMINAL_LOCAL_PERSISTENT — enables for local backend

Commands requiring stdin_data or sudo automatically fall back to one-shot mode.

Memory Configuration

memory:
  memory_enabled: true        # Toggle memory persistence
  user_profile_enabled: true
  memory_char_limit: 2200     # ~800 tokens
  user_char_limit: 1375       # ~500 tokens

Persistent memory stored in ~/.hermes/memories/ (MEMORY.md, USER.md).

File Read Safety

file_read_max_chars: 100000  # default, ~25-35K tokens

Controls maximum characters returned per file read operation. Prevents large files (minified JS, data dumps) from flooding the context window. Agent deduplicates reads; counter resets on context compression.

Git Worktree Isolation

worktree: true   # Always create a worktree (same as hermes -w flag)

Each session creates a fresh worktree under .worktrees/ with an isolated branch. Add a .worktreeinclude file in the repo root to list gitignored files that should be copied into each worktree.

Context Compression

compression:
  enabled: true
  threshold: 0.50                                    # Compress at 50% of context limit
  target_ratio: 0.20                                 # Preserve 20% as recent tail
  protect_last_n: 20                                 # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                           # auto, openrouter, nous, codex, main, etc.
  summary_base_url: null                             # Custom OpenAI-compatible endpoint

Iteration Budget Pressure

agent:
  max_turns: 90  # Max iterations per conversation turn

Warnings inject into the last tool result's JSON as _budget_warning to preserve prompt caching.

Context Pressure Warnings

Automatic, no configuration required.

Does not modify the message stream or inject into model context.

Credential Pool Strategies

credential_pool_strategies:
  openrouter: round_robin   # cycle through keys evenly
  anthropic: least_used     # pick least-used key

Auxiliary Models

Universal config pattern for all auxiliary tasks:

auxiliary:
  vision:          # Image analysis and browser screenshots
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
    download_timeout: 30   # Image HTTP download timeout (vision only)

  web_extract:     # Web summarization and text extraction
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  approval:        # Dangerous command classifier (smart approvals)
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  compression:     # Context compression summarizer
    timeout: 120

  session_search:  # Summarizes past session matches
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  skills_hub:      # Skill matching and search
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  mcp:             # MCP tool dispatch
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  flush_memories:  # Conversation summarization for persistent memory
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

Provider hierarchy: base_url (if set) overrides provider. "auto" selects best available. Supported providers: auto, openrouter, nous, codex, copilot, anthropic, main, zai, kimi-coding, minimax.

Reasoning Effort

agent:
  reasoning_effort: ""  # empty = medium (default)

Valid values: xhigh, high, medium (default), low, minimal, none.

Runtime overrides: /reasoning high, /reasoning none, /reasoning show, /reasoning hide.

Tool-Use Enforcement

agent:
  tool_use_enforcement: "auto"  # "auto" | true | false | ["model-substring", ...]

TTS Configuration

tts:
  provider: "edge"  # edge | elevenlabs | openai | neutts

  edge:
    voice: "en-US-AriaNeural"           # 322 voices, 74 languages

  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"

  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"                       # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # Override for compatible endpoints

  neutts:
    ref_audio: ''
    ref_text: ''
    model: "neuphonic/neutts-air-q4-gguf"
    device: cpu

Controls both the text_to_speech tool and spoken replies in voice mode.

Display Settings

display:
  tool_progress: all           # off | new | all | verbose
  tool_progress_command: false # Enable /verbose in gateway
  skin: default
  theme_mode: auto             # auto | light | dark
  streaming: false             # Stream tokens in real-time (CLI)
  show_reasoning: false        # Show model thinking tokens
  show_cost: false             # Show estimated $ cost
  bell_on_complete: false      # Terminal bell on task completion

Privacy

privacy:
  redact_pii: false  # Redact PII from LLM context

STT Configuration

stt:
  provider: "local"  # local | groq | openai
  local:
    model: "base"    # tiny, base, small, medium, large-v3
  openai:
    model: "whisper-1"  # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
  groq:
    # Uses GROQ_API_KEY automatically

Environment variable overrides:

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

Fallback chain: local → groq → openai if requested provider is unavailable.

Voice Mode (CLI)

voice:
  record_key: "ctrl+b"         # Push-to-talk key
  max_recording_seconds: 120   # Hard stop for long recordings
  auto_tts: false              # Enable spoken replies automatically with /voice on
  silence_threshold: 200       # RMS threshold for speech detection
  silence_duration: 3.0        # Seconds of silence before auto-stop

CLI commands: /voice on to enable microphone mode, press record_key to start/stop recording, /voice tts to toggle spoken replies.

Streaming

CLI

display:
  streaming: true          # Stream tokens to terminal in real-time
  show_reasoning: true     # Also stream reasoning/thinking tokens

Responses appear token-by-token in a streaming box. Falls back automatically if provider lacks streaming support.

Gateway (Telegram, Discord, Slack)

streaming:
  enabled: true            # Enable progressive message editing
  transport: edit          # "edit" or "off"
  edit_interval: 0.3       # Seconds between message edits
  buffer_threshold: 40     # Characters before forcing edit flush
  cursor: " ▉"             # Cursor shown during streaming

Bot sends message on first token, progressively edits as tokens arrive. Platforms lacking edit support auto-detect and gracefully disable.

Group Chat Session Isolation

group_sessions_per_user: true  # true = per-user isolation; false = shared session

• true (default): Each sender gets their own session in Discord channels, Telegram groups, and Slack channels (when platform provides user ID). DMs always per-user. Threads isolated from parent channel.
• false: One shared conversation per chat room.

Unauthorized DM Behavior

unauthorized_dm_behavior: pair  # pair | ignore

# Platform-specific override:
whatsapp:
  unauthorized_dm_behavior: ignore

Quick Commands

Define zero-argument shell commands invocable without consuming tokens:

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  disk:
    type: exec
    command: df -h /

30-second timeout — long-running commands are killed with an error message. Quick commands are checked before skill commands, so you can override skill names.

Human Delay

human_delay:
  mode: "off"        # off | natural | custom
  min_ms: 800        # Minimum delay in ms (custom mode)
  max_ms: 2500       # Maximum delay in ms (custom mode)

Simulates human-like response pacing in messaging platforms. natural uses preset ranges; custom allows explicit min/max milliseconds.

Code Execution

code_execution:
  timeout: 300          # Max execution time in seconds
  max_tool_calls: 50    # Max tool calls within code execution

Web Search Backends

web:
  backend: firecrawl  # firecrawl | parallel | tavily | exa

Backend is auto-detected from available API keys. Additional options:

• FIRECRAWL_API_URL — self-hosted Firecrawl instance URL
• PARALLEL_SEARCH_MODE — fast, one-shot, or agentic

Browser

browser:
  inactivity_timeout: 120     # Seconds before browser context closes
  command_timeout: 30         # Seconds per browser command
  record_sessions: false      # Auto-record sessions as WebM
  camofox:
    managed_persistence: false

Timezone

timezone: "America/New_York"  # IANA timezone (default: "" = server-local)

Affects timestamps in logs, cron scheduling, and system prompt time injection. Accepts any IANA timezone identifier.

Discord

discord:
  require_mention: true           # Require @mention in server channels
  free_response_channels: ""      # Comma-separated channel IDs (no mention required)
  auto_thread: true               # Auto-create threads on @mention

DMs always work without a mention. Free-response channels bypass the mention requirement.

Security

security:
  redact_secrets: true           # Redact API key patterns in tool output and logs
  tirith_enabled: true           # Enable Tirith command scanning
  tirith_path: "tirith"          # Path to tirith binary (default: "tirith" in $PATH)
  tirith_timeout: 5              # Seconds to wait before timing out
  tirith_fail_open: true         # Allow execution if tirith is unavailable
  website_blocklist:
    enabled: false
    domains: []                  # Exact or wildcard domain rules
    shared_files: []             # Paths to files with one rule per line

Blocklist supports: exact domains (admin.example.com), wildcard subdomains (*.internal.company.com), TLD wildcards (*.local). Policy cached for 30 seconds.

Smart Approvals

approvals:
  mode: manual  # manual | smart | off

Checkpoints

checkpoints:
  enabled: true         # Enable automatic checkpoints
  max_snapshots: 50     # Max checkpoints per directory

Automatic filesystem snapshots before destructive file operations.

Delegation

delegation:
  model: ""       # Override model for subagents (empty = inherit parent)
  provider: ""    # Override provider (empty = inherit parent)
  base_url: ""    # Direct OpenAI-compatible endpoint (highest precedence)
  api_key: ""     # API key for base_url (falls back to OPENAI_API_KEY)

Precedence: delegation.base_url → delegation.provider → parent provider. Setting only model changes the model within the same provider credentials.

Clarify

clarify:
  timeout: 120  # Seconds to wait for user clarification response

Controls how long Hermes waits for clarification when ambiguity requires user input.

Context Files (SOUL.md, AGENTS.md)

Priority (first match wins): .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. SOUL.md always loads independently. AGENTS.md is hierarchical — subdirectory files are combined. All context files capped at 20,000 characters with smart truncation.

Working Directory

MESSAGING_CWD=/home/myuser/projects   # Gateway sessions
TERMINAL_CWD=/workspace               # All terminal sessions

Defaults:

• CLI: directory where the command runs
• Messaging gateway: home directory ~
• Docker / Singularity / Modal / SSH: user's home inside container/remote

Related

• Security
• Tools & Toolsets
• Voice Mode
• MCP
• Memory
• CLI Commands

Configuration

Context Files

Hermes recognises five context file types. Only one project context type loads per session (first-match priority). SOUL.md always loads independently as a separate slot.

Supported File Types

Loading Priority

Project context files are resolved with first-match logic:

.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules

SOUL.md is always loaded as slot #1 independent of this priority order.

Progressive Subdirectory Discovery

As the agent navigates directories during a session it automatically discovers and injects relevant context files from subdirectories. Rules:

• Each subdirectory is checked once per session.
• Ancestor directories are walked up to 5 levels.
• Files surface only when the agent enters a relevant directory, preventing system prompt bloat.
• Prompt cache stability is maintained by deferring injection until needed.

Security Scanning

All context files are scanned for prompt injection threats before inclusion. Detected patterns:

• Instruction overrides ("ignore previous instructions")
• Deception patterns ("do not tell the user")
• Hidden or invisible characters
• Credential exfiltration attempts
• Commands to access secret files

Flagged files are blocked entirely and the user is notified.

Size Constraints

Best Practices

• Keep AGENTS.md concise with structured headers, concrete examples, explicit prohibitions, and key paths/ports.
• For monorepos, use nested AGENTS.md files per subdirectory rather than a single large root file.
• Reserve SOUL.md for stable, instance-wide personality — not project-specific instructions.
• Update context files regularly as the project evolves.

Related

• Personality
• Memory
• Skills

MCP (Model Context Protocol)

MCP lets Hermes connect to external tool servers — GitHub, databases, file systems, APIs — without requiring native integrations. Hermes can also expose itself as an MCP server for other agents.

Server Types

Configuration

MCP servers are defined in ~/.hermes/config.yaml under mcp_servers.

Tool Registration & Naming

Hermes prefixes MCP tools to prevent name collisions:

mcp_<server_name>_<tool_name>
# e.g. mcp_filesystem_read_file

Tool Filtering

# Whitelist — expose only these tools
tools:
  include: [read_file, list_directory]

# Blacklist — hide dangerous operations
tools:
  exclude: [delete_file]

# Disable resource/prompt wrappers
tools:
  resources: false
  prompts: false

The include list takes precedence when both include and exclude are specified.

Dynamic Tool Discovery

Servers can notify Hermes of runtime capability changes via notifications/tools/list_changed. Hermes automatically re-fetches and updates the tool registry without manual intervention.

Sampling

MCP servers can request LLM inference through Hermes.

Sampling is enabled by default; disable it per server in config.

Hermes as MCP Server

Hermes can expose itself as an MCP server, making its messaging capabilities available to other MCP-compatible agents (Claude Code, Cursor, etc.).

hermes mcp serve

Exposed tools: conversation listing, message reading, event polling, message sending, permission management.

Event system: supports polling and long-polling for near-real-time message awareness.

Current limitations: stdio transport only; text-only sends; no media attachment support.

Related

• Tools
• Skills

Memory

Hermes provides a two-file persistent memory system (MEMORY.md and USER.md) that injects into every session, plus a full-text session search index and optional external provider plugins.

Core Memory Files

Both files are stored in ~/.hermes/memories/ and injected as a frozen snapshot at session start. There is no explicit read action — content appears automatically in context.

Memory Tool Actions

What to Save vs. Avoid

Save:

• User preferences and corrections
• Environment configuration details
• Project conventions discovered during work
• Completed milestones
• Explicit user requests

Avoid:

• Trivial or commonly-known facts
• Large code blocks
• Temporary file paths
• Data already present in context files

Capacity Management

When a file exceeds its character limit the agent receives an error listing current entries. The agent must consolidate or remove entries before adding new ones. Best practice: consolidate when usage reaches 80% of the limit.

Session Search

The session_search tool queries a SQLite database at ~/.hermes/state.db using FTS5 full-text search across all past sessions. Results include Gemini Flash summaries to help locate specific discussions.

External Memory Providers

Seven plugins extend (never replace) the built-in memory system:

Configuration

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

Related

• Context Files
• Tools

Personality

Hermes uses a three-layer personality system. SOUL.md sets the persistent baseline identity; AGENTS.md provides project-specific context; /personality applies temporary session overlays.

SOUL.md

SOUL.md is located at ~/.hermes/SOUL.md (or $HERMES_HOME/SOUL.md). It occupies slot #1 in the system prompt — the first thing injected before any other context.

Behaviour:

• Auto-created with a starter template if it does not exist.
• User files are never overwritten by Hermes.
• Empty or unreadable files trigger fallback to the built-in identity.
• Content is injected verbatim after security scanning.
• Loaded only from HERMES_HOME, never from the current working directory.

What to include:

• Tone and communication style
• Directness level
• How to handle uncertainty
• Stylistic preferences
• Default interaction patterns

What to avoid (use AGENTS.md instead):

• One-off project instructions
• File paths or repository conventions
• Temporary workflow details

Three-Layer System

Built-In Personalities

14 presets ship with Hermes:

helpful, concise, technical, creative, teacher, kawaii, catgirl, pirate, shakespeare, surfer, noir, uwu, philosopher, hype

Activate with /personality <name>.

Custom Personalities

# ~/.hermes/config.yaml
agent:
  personalities:
    codereviewer: "You are a meticulous code reviewer..."
    docs-writer: "You write clear, concise technical documentation..."

Activate via /personality codereviewer.

Recommended Workflow

1. Maintain a thoughtful global SOUL.md for stable voice. 2. Place project-specific instructions in AGENTS.md. 3. Use /personality only for temporary shifts within a session.

Related

• Context Files

Features

Skills

Skills are on-demand knowledge documents following the agentskills.io open standard. They live in ~/.hermes/skills/ and are loaded progressively to minimise token usage.

Progressive Disclosure Architecture

The agent only loads deeper levels when the skill is genuinely needed.

SKILL.md Format

Skills use YAML frontmatter followed by structured markdown sections.

Frontmatter fields:

Content sections: When to Use, Procedure, Pitfalls, Verification.

Conditional Activation

# Shown only when web toolset has no API key
fallback_for_toolsets:
  - web

# Shown only when browser toolset is available
requires_toolsets:
  - browser

External Skill Directories

# ~/.hermes/config.yaml
skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

External directories are read-only. Local skills take precedence over external versions. Non-existent paths are silently ignored.

Agent-Managed Skills

Agents autonomously create and update skills via the skill_manage tool when:

• Completing complex workflows (5+ tool calls)
• Discovering non-trivial solutions after encountering errors
• Receiving corrections from the user

Available actions: create, patch (preferred), edit, delete, write_file, remove_file.

Skills Hub

hermes skills browse --source official
hermes skills search kubernetes --source skills-sh
hermes skills install openai/skills/k8s
hermes skills check    # detect upstream updates
hermes skills update   # reinstall changed skills

Security & Trust Levels

All hub skills are scanned for exfiltration, injection, destructive commands, and supply-chain threats.

The --force flag overrides non-dangerous policy blocks but cannot bypass dangerous verdicts.

Environment Variable Declaration

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: https://developers.google.com/tenor
    required_for: full functionality

Declared variables are automatically passed to execute_code and terminal sandboxes.

Directory Layout

~/.hermes/skills/
├── category/skill-name/
│   ├── SKILL.md          (required)
│   ├── references/
│   ├── templates/
│   ├── scripts/
│   └── assets/
├── .hub/                 (registry state, audit logs)
└── .bundled_manifest

Skills surface as slash commands (/skill-name) and respond to natural language queries.

Related

• Context Files
• MCP

Tools & Toolsets

Hermes organizes its capabilities into eight tool categories and exposes them through named toolsets. Terminals can run locally, in containers, or on remote infrastructure.

Tool Categories

Available Toolsets

Common preset names: web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, rl

Terminal Backends

Background Process Management

Start a process with background=true. Manage running processes via the process tool:

Container Resources

Configure CPU cores, memory (MB), disk (MB), and filesystem persistence when using container backends.

Security Features

• Read-only root filesystem
• Dropped Linux capabilities
• No privilege escalation
• PID limits enforced
• Full namespace isolation

Sudo Support

Sudo prompts are handled interactively (password cached for the session) or via the SUDO_PASSWORD environment variable for unattended use.

Related

• Memory
• MCP

Voice Mode

Hermes supports hands-free voice interaction in the CLI and through gateway platforms (Telegram, Discord). Both STT and TTS are pluggable with local or cloud providers.

CLI Voice Interaction

Activate recording with Ctrl+B (configurable). A beep signals the start. The system uses a two-stage silence detection algorithm:

1. Confirm speech is above the noise threshold for 0.3 seconds. 2. Wait 3 seconds of silence before stopping.

Two beeps signal recording completion. The agent can reply with text or spoken audio.

CLI commands:

Speech-to-Text (STT) Providers

Local processing: pip install faster-whisper (~150 MB model download). The system falls back automatically through available providers.

Text-to-Speech (TTS) Providers

Streaming TTS delivers responses sentence-by-sentence rather than waiting for full completion.

Gateway Voice (Telegram & Discord Text)

Voice bubbles are sent inline with text responses. Commands (/voice on, /voice tts, etc.) persist across restarts.

Discord Voice Channels

The bot joins voice channels for real-time conversation.

Required permissions: Connect + Speak (permissions integer 274881432640)

Required gateway intents: Presence, Server Members, Message Content

Opus codec: brew install opus (macOS) or sudo apt install libopus0 (Linux)

Commands (issued in a text channel):

How it works: The bot listens to each user independently, detects silence (1.5 s after 0.5 s of speech), transcribes via STT, processes through the agent pipeline, and replies via TTS. The listener is paused during TTS playback to prevent audio echo.

Access control: Discord voice is restricted to users listed in DISCORD_ALLOWED_USERS.

Configuration

# ~/.hermes/config.yaml
voice:
  record_key: "ctrl+b"
  silence_threshold: 200   # RMS level
  silence_duration: 3.0    # seconds
  auto_tts: false

# ~/.hermes/.env
GROQ_API_KEY=...
ELEVENLABS_API_KEY=...
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=user-id
DISCORD_REQUIRE_MENTION=false
DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

System Dependencies

Quality Features

• Hallucination filter: Removes 26 known phantom transcription phrases produced from silence.
• Real-time level display: Shows microphone input as ● [▁▂▃▅▇▇▅▂] ❯
• Continuous mode: Recording auto-restarts after agent responses without requiring another key press.

Related

• Personality
• Tools

Installation

Install Hermes Agent via a one-line script (Linux, macOS, WSL2) or manually in 10 steps. The automated installer handles all dependencies and has you running in under two minutes.

Signature / Usage

# Quick install (Linux, macOS, WSL2)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# After installation
hermes

Options / Props

Install with extras:

uv pip install -e ".[messaging,voice]"

Manual Installation Steps

1. Clone repository with submodules 2. Install uv and create a Python 3.11 virtual environment 3. uv pip install -e ".[all]" 4. Optionally install tinker-atropos submodule 5. npm install for browser / WhatsApp tools (optional) 6. Create config directories at ~/.hermes/ 7. Add API keys to ~/.hermes/.env (minimum: LLM provider key) 8. Symlink hermes command to PATH 9. hermes model — configure LLM provider 10. hermes doctor — verify installation

Post-Installation Commands

Notes

• Native Windows is not supported; use WSL2.
• Only Git is required before running the quick installer — all other dependencies (Python 3.11 via uv, Node.js v22, ripgrep, ffmpeg) are detected and installed automatically.
• The installer sets up a virtual environment and configures a global hermes command.
• If hermes is not found after install, reload your shell (source ~/.bashrc or source ~/.zshrc).

Related

• Quickstart
• Learning Path

Learning Path

Navigate Hermes Agent documentation by experience level or specific use case.

Paths by Experience Level

Use-Case Pathways

Feature Directory

12 major capability areas with dedicated documentation:

Tools, Skills, Memory, Code Execution, Browser, Cron Scheduling, Delegation, MCP, Hooks, Batch Processing, RL Training, Provider Routing.

Recommended Progression

1. Installation 2. Quickstart 3. CLI usage 4. Customization (tools, skills, memory) 5. Advanced features (scheduling, delegation, MCP) 6. Development and contribution

Notes

• Three navigation entry points are provided on the page: by experience level, by use-case goal, and a full feature overview table.
• The learning path page links directly to each feature's detailed documentation section.

Related

• Installation
• Quickstart

Quickstart

Start using Hermes Agent in a terminal with a chosen LLM provider, built-in tools, and slash commands after a one-line install.

Signature / Usage

# Install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Configure provider
hermes model

# Start chatting
hermes

Key Commands

Slash Commands (in-session)

Type / inside a chat session to trigger autocomplete:

Supported LLM Providers

15+ providers with no vendor lock-in:

• Nous Portal (subscription)
• OpenAI, Anthropic, OpenRouter
• Hugging Face (open-source models)
• Custom endpoints: VLLM, Ollama, etc.

Advanced Capabilities

Notes

• Use Alt+Enter or Ctrl+J for multi-line input (e.g., pasting code blocks).
• Windows users must install WSL2 before running the installer.
• Provider configuration can be changed at any time with hermes model or /model inside a session.

Related

• Installation
• Learning Path

Getting Started

Using MCP with Hermes Agent

Guide for integrating Model Context Protocol (MCP) servers with Hermes, including setup, filtering strategies, and common patterns.

When to Use MCP

Use MCP when:

• A tool already exists in MCP form and you do not want to build a native Hermes tool
• Operating against local/remote systems through an RPC layer is needed
• Fine-grained per-server exposure control matters
• Connecting to internal APIs without modifying Hermes core

Avoid MCP when:

• Built-in tools already solve the problem effectively
• The server exposes dangerous functionality without adequate filtering capability
• A single narrow integration would be simpler via native tooling

Signature / Usage

Installation

If installed via standard script, MCP is included. To add separately:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

Ensure Node.js/npx (for JavaScript servers) and uvx (for Python servers) are available.

Setup Progression

Step 1 — Add a single safe server (filesystem access to a bounded directory):

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

Step 2 — Verify loading:

• Check the Hermes banner for MCP integration status
• Query available tools: "Tell me which MCP-backed tools are available right now"
• Use /reload-mcp after configuration changes

Step 3 — Implement filtering:

Whitelist approach (recommended for sensitive systems):

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

Blacklist approach (for excluding specific actions):

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

Disable utility wrappers:

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

Options / Props

Filtering Keys

Notes

• Prefer whitelists (tools.include) for financial, customer-facing, or destructive operations
• Scope servers narrowly: restrict filesystem servers to specific directories, git servers to single repositories
• Disable unused utilities (resources: false, prompts: false) to reduce tool surface
• Execute /reload-mcp after modifying include/exclude lists, flags, or authentication
• Use enabled: false to preserve configuration without connecting

Common Patterns

Local project assistant:

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

GitHub triage:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

Internal API assistant:

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

Troubleshooting

Recommended First Servers

Good starting choices: filesystem, git, GitHub, documentation servers, narrow internal APIs.

Avoid initially: large enterprise systems with destructive actions and no filtering options.

Related

• MCP Feature Reference
• Configuration
• Security

Guides

Tips & Best Practices

Practical guidance for getting the most out of Hermes Agent across prompting, CLI usage, context files, memory/skills, performance, messaging, and security.

Prompting

• Be specific: Include file paths, error messages, and expected behavior upfront rather than iterating through clarification rounds.
• Front-load context: Detailed prompts reduce iteration cycles significantly.
• Use AGENTS.md: Store recurring instructions in an AGENTS.md at the project root — the agent reads it automatically each session.
• Let the agent explore: Allow independent use of file search, terminal access, and code execution rather than directing every step manually.
• Check existing skills: Run /skills before writing lengthy procedural prompts; a pre-built skill may already exist.

CLI Power User Tips

Context Files

`AGENTS.md` (project-level): Store architecture decisions, coding conventions, and project-specific rules. Injected automatically into every session. In monorepos, all AGENTS.md files at every directory level are discovered and concatenated.

`SOUL.md` (global, `~/.hermes/SOUL.md`): Customize the agent's default behavior globally — communication style, technical preferences, response patterns.

*`.cursorrules` / `.cursor/rules/.mdc`:** Hermes reads these automatically, eliminating duplication across tools.

Memory & Skills

• Memory for facts: Store environment details, preferences, project locations.
• Skills for procedures: Use skills for multi-step workflows that recur (5+ steps is a good threshold).
• Creating skills: Ask the agent to save a task as a skill; invoke later with /skill-name.
• Memory capacity: MEMORY.md is bounded (~2,200 characters) and USER.md (~1,375 characters). Request consolidation when full: "clean up your memory."
• Persistent learning: After productive sessions, ask the agent to "remember this for next time."

Performance & Cost

• Prompt cache stability: Keep system prompts and context files consistent within sessions to maximize provider cache hits.
• Compress history: Use /compress to summarize conversation history when token accumulation slows responses.
• Parallel delegation: Use delegate_task for concurrent subtasks — each subagent maintains independent context and returns only final summaries.
• Batch operations: Write scripts executing multiple operations atomically rather than running terminal commands sequentially.
• Model selection: Use /model to switch — frontier models (Claude Sonnet/Opus, GPT-4o) for complex reasoning; faster models for boilerplate, formatting, renaming.
• Usage monitoring: /usage for token consumption snapshots; /insights for 30-day usage pattern analysis.

Messaging Tips

• Home channel: Use /sethome to designate a primary Telegram or Discord channel for cron job results and scheduled outputs.
• Session naming: Use /title to name sessions descriptively (e.g., "auth-refactor") for easy discovery via hermes sessions list and resumption via hermes -r "name".
• Team DM pairing: Enable DM pairing to allow teammates to self-serve with one-time pairing codes (approve via hermes pairing approve telegram XKGH5N7P).
• Verbose mode: Use /verbose to cycle display modes — all for comprehensive live output in CLI, new for messaging platforms to minimize noise.

Security

• Docker for untrusted code: Set TERMINAL_BACKEND=docker in .env when handling unfamiliar repositories to contain destructive commands.
• Command approval caution: When dangerous commands trigger approval prompts, choose "session" scope before considering "always" allowlisting.
• Command safety checks: Hermes validates commands against dangerous patterns (recursive deletes, SQL drops, shell piping). Never disable in production.
• Container security exception: Dangerous command checks are skipped in container backends (Docker, Singularity, Modal) since the container provides the security boundary.
• Messaging bot allowlists: Never enable GATEWAY_ALLOW_ALL_USERS=true for bots with terminal access. Use TELEGRAM_ALLOWED_USERS, DISCORD_ALLOWED_USERS, or DM pairing instead.
• Windows UTF-8: Explicitly open files with UTF-8 encoding to avoid UnicodeEncodeError on Windows systems using default encodings.

Related

• CLI Interface
• Configuration
• Memory
• Skills
• Context Files
• Security

Voice Mode with Hermes Agent

Guide for enabling and configuring voice interaction in Hermes, covering CLI microphone input, messaging platform voice replies, and Discord voice channel integration.

Three Voice Modes

Signature / Usage

Installation

# CLI voice input/output
pip install "hermes-agent[voice]"

# Messaging platform support
pip install "hermes-agent[messaging]"

# Premium TTS providers
pip install "hermes-agent[tts-premium]"

# All features
pip install "hermes-agent[all]"

System dependencies:

macOS: install via Homebrew. Ubuntu/Debian: install via apt.

Core Configuration

voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120
  auto_tts: false
  silence_threshold: 200
  silence_duration: 3.0
stt:
  provider: "local"
  local:
    model: "base"
tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

Options / Props

STT/TTS Provider Selection

Voice Configuration Keys

Notes

CLI Voice Workflow

Press record hotkey (default Ctrl+B) → speak → silence auto-stops recording → transcription runs → agent responds with spoken output.

Useful for debugging, research, and accessibility scenarios.

Tuning tips:

• Increase silence_threshold if background noise triggers early stops
• Increase silence_duration if you pause between sentences
• Rebind record_key to avoid terminal conflicts

Messaging Platform Setup

Start the gateway: hermes gateway

Enable voice in chat with /voice on or /voice tts.

Voice modes:

• off — text only
• voice_only — speak only on voice input
• all — always speak

Discord Voice Channel Setup

Required bot permissions: Connect, Speak, Voice Activity. Required privileged intents: Presence, Server Members, Message Content.

/voice join    # Join the current voice channel
/voice leave   # Leave the voice channel
/voice status  # Check current voice state

When joined, Hermes listens to user speech, transcribes it, runs the agent pipeline, and speaks replies back.

Recommended Onboarding Path

1. Verify text-mode Hermes works 2. Install voice extras 3. Test CLI mode with local STT + Edge TTS 4. Enable chat voice replies 5. Attempt Discord VC only after the above succeeds

This progression keeps the debugging surface small.

Troubleshooting

Related

• Voice Mode Feature Reference
• Personality
• Configuration

Messaging Gateway

A single background process that connects to all configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

Signature / Usage

hermes gateway                         # Run in foreground
hermes gateway setup                   # Interactive configuration
hermes gateway install                 # Install as user service (Linux/macOS)
sudo hermes gateway install --system   # Install as boot-time service (Linux)
hermes gateway start/stop/status       # Manage running service

Supported Platforms

Telegram, Discord, Slack, WhatsApp, Signal, SMS (Twilio), Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom (Enterprise WeChat), Open WebUI.

Platform Feature Comparison

Chat Commands

Session Management

Sessions persist conversation context across messages until reset.

Reset policies:

Platform-specific overrides in ~/.hermes/gateway.json:

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

Security

Authorization

By default the gateway denies unauthorized users unless they are explicitly allowlisted or paired via DM.

# Environment variable allowlisting
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
GATEWAY_ALLOWED_USERS=123456789,987654321
GATEWAY_ALLOW_ALL_USERS=true  # Not recommended for terminal-access bots

DM Pairing

Unknown users who send a direct message receive a one-time pairing code. Codes expire after one hour and are cryptographically randomized.

hermes pairing list                          # View pending/approved users
hermes pairing approve telegram XKGH5N7P    # Approve by code
hermes pairing revoke telegram 123456789    # Revoke by user ID

Background Sessions

Run independent tasks asynchronously without blocking the main chat. Each /background invocation spawns a separate agent instance with isolated session storage, inheriting the current model and provider configuration.

/background <prompt>

Results are delivered to the originating channel prefixed with "✅ Background task complete" or "❌ Background task failed".

Notification frequency in ~/.hermes/config.yaml:

display:
  background_process_notifications: all  # all | result | error | off

Service Management

Linux (systemd)

hermes gateway install                      # Install as user service
hermes gateway install --system             # Install as boot-time system service
journalctl --user -u hermes-gateway -f      # Stream logs
sudo loginctl enable-linger $USER           # Persist service after logout

macOS (launchd)

hermes gateway install                      # Install as launchd agent
tail -f ~/.hermes/logs/gateway.log          # Stream logs

The plist is written to ~/Library/LaunchAgents/ai.hermes.gateway.plist and includes PATH, VIRTUAL_ENV, and HERMES_HOME variables.

Platform-Specific Toolsets

Notes

• GATEWAY_ALLOW_ALL_USERS=true is not recommended for bots with terminal access.
• Pairing codes expire after one hour; approve them promptly.
• Background tasks inherit the model/provider of the session that spawned them but run in fully isolated storage.
• On macOS, hermes gateway install writes a launchd plist; on Linux without --system it installs a systemd user unit.

Related

• Security
• Voice Mode
• Configuration
• CLI Commands

Messaging

FAQ & Troubleshooting

Frequently asked questions, troubleshooting guidance, and workflow patterns for Hermes Agent.

Frequently Asked Questions

LLM Provider Support

Hermes works with any OpenAI-compatible API, including OpenRouter, Nous Portal, OpenAI, Anthropic, Google, z.ai/ZhipuAI, Kimi/Moonshot AI, MiniMax, and local models via Ollama, vLLM, llama.cpp, SGLang, or any OpenAI-compatible server.

Windows Compatibility

Hermes requires a Unix-like environment. Install WSL2 and run Hermes from within it using the standard installation script.

Data Privacy

API calls go only to the LLM provider you configure. Hermes Agent does not collect telemetry, usage data, or analytics. Conversations, memory, and skills are stored locally.

Offline & Local Models

Configure custom endpoints using hermes model and select the Custom endpoint option. Supported backends: Ollama, vLLM, llama.cpp server, SGLang, and LocalAI.

Cost

Hermes Agent itself is free and open-source (MIT license). You pay only for LLM API usage from your chosen provider. Local models are completely free.

Multi-User Access

Multiple users can interact with the same Hermes Agent instance via Telegram, Discord, Slack, WhatsApp, or Home Assistant. Access is controlled through allowlists and DM pairing.

Memory vs. Skills

• Memory: stores facts — things the agent knows about you
• Skills: stores procedures — step-by-step instructions for how to do things

Python Integration

Developers can import the AIAgent class and use Hermes programmatically within their own projects.

Troubleshooting

Installation Issues

Provider & Model Issues

Terminal Issues

Messaging Issues

Performance Issues

MCP Issues

Profiles

Profiles provide a managed layer on top of HERMES_HOME, handling directory structure, shell aliases, and skill updates across profiles.

Key Behaviors

• Bot token sharing: Each messaging platform requires exclusive access to a bot token. If two profiles try to use the same token simultaneously, the second gateway will fail.
• Data isolation: Each profile has its own memory store, session database, and skills directory. They are completely isolated.
• Update behavior: hermes update pulls latest code and reinstalls dependencies once, then syncs updated skills to all profiles.
• Profile movement: Export with hermes profile export, then import on another machine.
• Profile capacity: No hard limit; practical limit depends on disk space and concurrent gateways the system can handle.

Workflows & Patterns

Multi-Model Workflows

Configure delegation in config.yaml to route subagents to specific models automatically.

WhatsApp Per-Chat Binding

Current limitation prevents multiple profiles on one number. Workarounds: personality switching, cron jobs, separate numbers, or switching to Telegram/Discord.

Telegram Display Control

Adjust display.tool_progress to off, new, all, or verbose.

Telegram Skill Limits

Disable unused skills via hermes skills config to stay under the 100-command limit.

Shared Thread Sessions

Slack supports thread-based sessions for multiple users. Discord supports channel-based sharing.

Machine Export

Use profile export/import or sync the ~/.hermes/ directory (excluding the hermes-agent subdirectory).

Common Errors

• HTTP 400: Usually indicates model mismatch or insufficient API key permissions on the provider side.
• Shell permission issues: Fix with chmod 644 ~/.zshrc if needed.

Related

• Skills Hub

Reference

Skills Hub

The Skills Hub is the catalog and management interface for Hermes Agent skills — reusable procedure files that extend the agent's capabilities for specialized tasks.

Overview

How Skills Work

Skills store procedures — step-by-step instructions for how to do things (as opposed to Memory, which stores facts). Users discover, search, and install skills from multiple registries to customize their agent for specific workflows without starting from scratch.

Manage skills via:

hermes skills config      # enable / disable installed skills
hermes skills install     # install a skill from a registry

Categories

Registry Sources

• Built-in (75): Core skills shipped with Hermes Agent covering GitHub management, ML/AI operations, creative tools, and productivity integrations.
• Optional (45): Additional official skills not enabled by default.
• LobeHub (505): Third-party community registry.
• Anthropic (16): Skills provided by Anthropic.

Notes

• Telegram deployments are limited to 100 commands per bot; disable unused skills via hermes skills config to stay within this limit.
• Skills are stored per-profile and are fully isolated between profiles.

Related

• FAQ & Troubleshooting

Security

Security

Hermes Agent implements a defense-in-depth architecture across five distinct security boundaries, covering everything from user authorization through container isolation to prompt injection prevention.

5-Layer Defense Model

---

Dangerous Command Approval

Approval Modes

Configured via approvals.mode in ~/.hermes/config.yaml:

approvals:
  mode: manual    # manual | smart | off
  timeout: 60     # seconds to wait for user response (default: 60, fail-closed on timeout)

YOLO Mode

Bypasses all dangerous command approval prompts for the session.

Use only in fully trusted environments.

Dangerous Patterns

The following patterns trigger the approval flow:

Note: When running in docker, singularity, modal, or daytona backends, dangerous command checks are skipped — the container itself provides the security boundary.

Approval Flow (CLI)

Warning  DANGEROUS COMMAND: recursive delete
  rm -rf /tmp/old-project
  [o]nce  |  [s]ession  |  [a]lways  |  [d]eny
  Choice [o/s/a/D]:

Approval Flow (Gateway / Messaging)

Dangerous command details are sent to chat. Respond with:

• Approve: yes, y, approve, ok, go
• Deny: no, n, deny, cancel

HERMES_EXEC_ASK=1 is set automatically when running via the gateway.

Permanent Allowlist

Commands approved with always are saved to ~/.hermes/config.yaml:

command_allowlist:
  - rm
  - systemctl

Edit via hermes config edit.

---

User Authorization (Gateway)

Authorization Check Order

_is_user_authorized() evaluates in this sequence:

1. Per-platform allow-all flag (e.g., DISCORD_ALLOW_ALL_USERS=true) 2. DM pairing approved list 3. Platform-specific allowlists (e.g., TELEGRAM_ALLOWED_USERS) 4. Global allowlist (GATEWAY_ALLOWED_USERS) 5. Global allow-all (GATEWAY_ALLOW_ALL_USERS=true) 6. Default: deny

Platform Allowlists

Set in ~/.hermes/.env:

TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=111222333444555666
WHATSAPP_ALLOWED_USERS=15551234567
SLACK_ALLOWED_USERS=U01ABC123
GATEWAY_ALLOWED_USERS=123456789

# Allow-all flags (use with caution)
DISCORD_ALLOW_ALL_USERS=true
GATEWAY_ALLOW_ALL_USERS=true

If no allowlists are configured and GATEWAY_ALLOW_ALL_USERS is unset, all users are denied. The gateway logs a warning at startup.

DM Pairing System

Code-based authorization for unknown users without requiring user IDs upfront.

Flow: 1. Unknown user sends a DM to the bot 2. Bot replies with an 8-character pairing code 3. Bot owner runs hermes pairing approve <platform> <code> 4. User is permanently approved for that platform

Configuration (~/.hermes/config.yaml):

unauthorized_dm_behavior: pair  # pair | ignore

# Override per platform
whatsapp:
  unauthorized_dm_behavior: ignore

Security Properties:

CLI Commands:

hermes pairing list                          # List pending and approved users
hermes pairing approve telegram ABC12DEF     # Approve a pending code
hermes pairing revoke telegram 123456789     # Revoke an approved user
hermes pairing clear-pending                 # Clear all pending requests

Storage in ~/.hermes/pairing/:

• {platform}-pending.json — pending pairing requests
• {platform}-approved.json — approved users
• _rate_limits.json — rate limit and lockout tracking

---

Container Isolation

Docker Security Hardening

Every container is launched with the following security arguments (from tools/environments/docker.py):

_SECURITY_ARGS = [
    "--cap-drop", "ALL",                               # Drop ALL Linux capabilities
    "--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
]

Resource Configuration

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_forward_env: []   # Explicit allowlist only; default: nothing forwarded
  container_cpu: 1         # CPU cores
  container_memory: 5120   # MB (default: 5 GB)
  container_disk: 51200    # MB (default: 50 GB)
  container_persistent: true  # Persist filesystem across sessions

Filesystem Persistence

---

Terminal Backend Security Comparison

For production deployments, prefer docker, modal, or daytona to isolate agent commands from the host.

---

Environment Variable & Credential Handling

Passthrough Mechanisms

1. Skill-scoped passthrough (automatic)

Skills declaring required_environment_variables in SKILL.md frontmatter have those variables automatically registered and passed through if set:

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor

2. Config-based passthrough (manual)

For variables not declared by skills:

terminal:
  env_passthrough:
    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

Credential File Passthrough

Declared in skill 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

Or manually in config:

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

Paths are relative to ~/.hermes/; they are mounted at /root/.hermes/ inside containers, read-only.

Sandbox Filtering Behavior

Notes

• Passthrough only affects explicitly declared variables; default security posture is unchanged
• Credential files are mounted read-only in Docker containers
• Skills Guard scans skill content for suspicious env access before installation
• Missing or unset variables are never registered and cannot leak

---

MCP Security

Safe Environment Variables for MCP Subprocesses

Only the following are passed from host to MCP stdio subprocesses:

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

All other variables (API keys, tokens, secrets) are stripped. Variables declared in the MCP server's env config are passed explicitly:

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

Credential Redaction

Error messages 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= URL/query parameters

---

Website Blocklist

Restrict which websites are accessible via web and browser tools:

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

Enforced across web_search, web_extract, browser_navigate, and all URL-capable tools. Blocked URLs return an error explaining the domain is blocked by policy.

---

SSRF Protection

All URL-capable tools validate URLs before fetching to prevent Server-Side Request Forgery. Blocked address ranges:

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 Scanning

Integrates tirith for content-level command scanning before execution.

Detects:

• 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 (cosign provenance verification if available).

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

Notes

• When tirith_fail_open: true (default), commands proceed if tirith is unavailable
• Set tirith_fail_open: false in high-security environments to block when unavailable
• Tirith verdict integrates with the approval flow: safe commands pass through; suspicious/blocked commands trigger user approval with full findings (severity, title, description, safer alternatives)
• Default choice is deny for unattended/automated scenarios

---

Context File Injection Protection

Context files (AGENTS.md, .cursorrules, SOUL.md) are scanned for prompt injection before inclusion in the system prompt.

Detected patterns:

• 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 display a warning instead of their content:

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

---

Production Deployment Best Practices

Gateway Deployment Checklist

1. Set explicit allowlists — never use GATEWAY_ALLOW_ALL_USERS=true 2. Use a container backend — set terminal.backend: docker 3. Restrict resource limits — set appropriate CPU, memory, and disk limits 4. Store secrets securely — keep API keys in ~/.hermes/.env with proper permissions (chmod 600) 5. Enable DM pairing — use pairing codes instead of hardcoding user IDs 6. Review the command allowlist — periodically audit command_allowlist 7. Set `MESSAGING_CWD` — prevent the agent from operating 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

chmod 600 ~/.hermes/.env
# Use separate keys per service
# Never commit .env files to version control

Network Isolation

Run the gateway on a separate machine or VM, using the SSH backend:

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

This keeps messaging connections separate from command execution.

Related

• Configuration
• Messaging Gateway
• Tools & Toolsets
• MCP
• Context Files