Hermes Agent: The Practitioner's Reference (2026)

TL;DR: Hermes Agent is an open-source self-improving AI agent from Nous Research. It runs as a CLI and as a multi-platform messaging gateway, stores a durable identity and persistent memory on disk, aggregates skills that improve with use, and works with any OpenAI-compatible LLM provider — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Alibaba, Hugging Face, Google, or your own self-hosted endpoint.¹² The hardest part for most new users is provider authentication: Hermes supports ~19 first-class providers plus custom endpoints, and three distinct auth paths (API key in .env, OAuth via hermes model, or custom endpoint in config.yaml). The auth model is the thing to learn first — everything else is downstream of which provider is resolved.

Hermes Agent operates as a full agent runtime, not a chat wrapper. It reads your filesystem, executes commands in sandboxed backends, scrapes the web, spawns subagents, runs scheduled cron jobs, talks to Telegram/Discord/Slack/WhatsApp/Signal/Email from a single gateway process, and creates its own skills from experience.¹ The CLI is a terminal UI built on top of a conversation loop in run_agent.py; the gateway is a long-running process that routes messages from messaging platforms through the same conversation loop.³

The difference between casual and expert Hermes usage comes down to five systems. Master these and Hermes becomes a force multiplier:

1. Provider resolution: how auth flows map to API calls
2. Configuration hierarchy: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool + toolset system: what the agent can do, gated per platform
4. Skills system: procedural memory the agent creates and evolves
5. Gateway + cron + profiles: running Hermes where you live, not just where you are

Key Takeaways

• Provider auth is three paths, not one. API key in .env, OAuth via hermes model/hermes auth, or custom endpoint in config.yaml. Pick the path that matches your provider, not the one that feels familiar.
• Switching providers is a single command. hermes model interactively walks you through every supported provider including OAuth logins, and /model provider:model switches mid-session without losing history.²
• Two files are the user-editable config surface. ~/.hermes/config.yaml holds settings and ~/.hermes/.env holds secrets. auth.json, SOUL.md, MEMORY.md, and skills/ are managed by Hermes directly — you can edit SOUL.md by hand, but the rest is touched by the agent itself.⁴
• Hermes is the successor to OpenClaw. If you’re migrating, hermes claw migrate imports 30+ categories of state automatically.⁵
• Quality of service depends on your auxiliary model. Vision, web summarization, compression, and memory flush all use a separate auxiliary LLM. By default this is Gemini Flash via auto-detection (OpenRouter → Nous → Codex) — if none of those are configured, these features degrade silently until you point the auxiliary slots at your main provider.⁴

Every section below is grounded in the upstream documentation at hermes-agent.nousresearch.com/docs and the source tree at github.com/NousResearch/hermes-agent. Every factual claim has a footnote pointing at the specific upstream page it came from.

Choose Your Path

How Hermes Works: The Mental Model

Hermes is structured around a single conversation loop that any entry point can invoke. The entry points are the CLI (cli.py), the messaging gateway (gateway/run.py), the ACP adapter for editor integration, the batch runner, and an API server.³ All of them ultimately call AIAgent.run_conversation() in run_agent.py, which:

1. Builds the system prompt from SOUL.md, MEMORY.md, USER.md, skills, context files, and tool guidance via prompt_builder.py³
2. Resolves the runtime provider via runtime_provider.py — this is the step that picks your auth, base URL, and API mode³
3. Calls the provider using one of three API modes: chat_completions, codex_responses, or anthropic_messages³
4. Dispatches any returned tool calls through model_tools.py and the central tool registry (tools/registry.py)³
5. Loops until the model produces a final response, then persists the session to SQLite with FTS5³

Understanding this loop matters because every feature — personalities, memory, skills, compression, fallback — attaches to one of these stages. When you’re reading a config key and wondering what it does, the answer is usually “it’s a knob on stage 1, 2, 3, or 4 of the loop above.”

Platform-agnostic core. One AIAgent class serves CLI, gateway, ACP, batch, and API server. Platform differences live in the entry point, not in the agent itself.³ This is why the same slash commands work in the terminal and in Telegram — they’re dispatched from a shared COMMAND_REGISTRY in hermes_cli/commands.py.⁶

The directory structure is the system. Hermes stores everything under ~/.hermes/ (or $HERMES_HOME for non-default profiles):⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

Every file above has a specific role; none of them overlap. If you’re looking for “where does Hermes store X,” it’s one of these.

Installation

The one-line installer is the path for 95% of users. It handles Python, uv, Node.js, ripgrep, ffmpeg, the repo clone, the virtual environment, and the global hermes command.⁷

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

Works on Linux, macOS, WSL2, and Android/Termux (the installer auto-detects Termux and switches to a tested Android bundle).⁷ Native Windows is not supported — install WSL2 and run the command above from there.⁷

After it finishes:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

The only prerequisite is git. The installer auto-provisions Python 3.11 via uv (no sudo required), Node.js v22 (for browser automation and the WhatsApp bridge), ripgrep, and ffmpeg.⁷

Verify the install

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor tells you exactly what’s missing and how to fix it.⁷ hermes dump is the diagnostic command to paste into a GitHub issue or Discord thread when asking for help — it’s a plain-text summary of your entire setup with secrets redacted.⁸

Manual installation

If you need full control — custom Python version, specific extras, Nix/NixOS integration — the manual flow is documented step-by-step in the upstream installation guide.⁷ Key optional extras you can combine with uv pip install -e ".[<extras>]":

Termux install command is different — it uses pip with a constraints file, not uv pip:

python -m pip install -e ".[termux]" -c constraints-termux.txt

This is because .[all] on Android pulls faster-whisper via the voice extra, which depends on ctranslate2 wheels that aren’t published for Android.⁷

Authentication & Providers

Hermes supports ~19 first-class providers plus custom endpoints, and three distinct auth paths. Here is the whole auth surface, organized by path so you can find the one that matches what you have.

The Three Auth Paths

Every provider in Hermes fits into one of three authentication patterns:

Path 1 — API key in .env. Put your key in ~/.hermes/.env and Hermes reads it on startup. Used by OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (and MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini, and most third-party providers.²

Path 2 — OAuth via hermes model or hermes auth. Launches a device code flow, opens a browser, stores credentials in ~/.hermes/auth.json (and can import existing credentials from tools like Claude Code or Codex CLI). Used by Nous Portal, OpenAI Codex (ChatGPT account), GitHub Copilot, and Anthropic (Claude Pro/Max).²

Path 3 — Custom endpoint in config.yaml. For any OpenAI-compatible API — Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM proxy, Together AI, Groq, Azure OpenAI, or your own self-hosted server. Configured once via hermes model → Custom endpoint, then persisted to config.yaml.²

The Full Provider Matrix

This is the complete list of first-class providers, with the exact setup flow for each.²

Anthropic: Three Auth Methods

Anthropic gets its own section because Hermes supports three distinct paths into Claude, and picking the right one matters. From the upstream docs:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

When you choose Anthropic OAuth through hermes model, Hermes prefers Claude Code’s own credential store over copying the token into ~/.hermes/.env. That keeps refreshable Claude credentials refreshable.² If you already use Claude Code on the same machine, this is the cleanest path.

To pin Anthropic permanently in config.yaml:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude and --provider claude-code also work as shorthand for --provider anthropic.²

GitHub Copilot: Two Modes

Copilot is supported in two modes: direct Copilot API (recommended) and Copilot ACP (which spawns the local Copilot CLI as a subprocess).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

Authentication is checked in this order, per the upstream docs:² 1. COPILOT_GITHUB_TOKEN environment variable 2. GH_TOKEN environment variable 3. GITHUB_TOKEN environment variable 4. gh auth token CLI fallback 5. OAuth device code login via hermes model

Token type matters. The Copilot API does not support classic Personal Access Tokens (ghp_*). Supported types are OAuth tokens (gho_*), fine-grained PATs (github_pat_* with Copilot Requests permission), and GitHub App tokens (ghu_*). If your gh auth token returns a ghp_* token, use hermes model to authenticate via OAuth instead.²

Chinese AI Providers (First-Class Support)

Hermes has built-in support for z.ai/GLM, Kimi/Moonshot, MiniMax (global + China endpoints), and Alibaba Cloud with dedicated provider IDs.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

Base URLs can be overridden with GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL, or DASHSCOPE_BASE_URL environment variables.²

Z.AI auto-detects the endpoint. When using the z.ai/GLM provider, Hermes probes multiple endpoints (global, China, coding variants) to find one that accepts your API key. The working endpoint is cached automatically — no GLM_BASE_URL needed for most users.²

xAI (Grok) automatically enables prompt caching. When the base URL contains x.ai, Hermes sends the x-grok-conv-id header with every request to route to the same server within a conversation session, reusing cached system prompts and history.² Automatic; no config needed.

The hermes auth Command

hermes auth is the credential management command for pools and OAuth credentials.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Credential pools are how you rotate multiple API keys or OAuth tokens for the same provider — useful for distributing rate limits across multiple keys without changing code.⁶ The legacy hermes login / hermes logout commands have been removed; use hermes auth instead.⁶

Custom & Self-Hosted Endpoints

Hermes works with any OpenAI-compatible API endpoint. If a server implements /v1/chat/completions, you can point Hermes at it.²

Interactive setup (recommended):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

Manual config.yaml:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Both approaches persist to config.yaml, which is the single source of truth for main-model, provider, and base URL.² The legacy env vars OPENAI_BASE_URL and LLM_MODEL are no longer read for main-model configuration — use hermes model or edit config.yaml directly.² (OPENAI_BASE_URL + OPENAI_API_KEY are still honored as a fallback for the auxiliary provider: "main" routing path, so don’t delete them blindly if you’re using them there.)⁴

Switching custom endpoints mid-session:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (bare, no model name) queries your endpoint’s /v1/models API and auto-selects the model if exactly one is loaded — useful for local servers running a single model.²

Local LLM Servers (Setup Templates)

The upstream docs have full setup guides for Ollama, vLLM, SGLang, llama.cpp, and LM Studio. Here are the key commands you’ll actually run. Each is designed to produce a working endpoint that Hermes can point at.²

Ollama — easiest local path, zero config:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Critical Ollama gotcha: Ollama defaults to very low context lengths (4,096 tokens under 24GB VRAM). You must raise it via OLLAMA_CONTEXT_LENGTH or a Modelfile — the OpenAI-compatible API does not accept context length from the client, so Hermes cannot set it for you.² For agent use, set at least 16k–32k.

vLLM — high-performance GPU serving:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Tool calling requires --enable-auto-tool-choice and --tool-call-parser <name>. Supported parsers: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Without these flags, tool calls will come back as plain text.²

SGLang — fast serving with RadixAttention for KV cache reuse:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLang gotcha: Default max_tokens is 128. Set --default-max-tokens on the server or configure model.max_tokens in config.yaml if responses get cut off.²

llama.cpp / llama-server — CPU and Apple Silicon Metal:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja is required for tool calling. Without it, llama-server ignores the tools parameter entirely and the model tries to call tools by writing JSON in its response text — which Hermes can’t parse as actual tool calls.²

LM Studio — desktop app with GUI:

Start the server from the LM Studio app (Developer tab → Start Server), or via CLI: lms server start (starts on port 1234) and lms load qwen2.5-coder --context-length 32768.² Then point hermes model at http://localhost:1234/v1.

Critical LM Studio gotcha: LM Studio reads context length from model metadata, but many GGUF models report 2048 or 4096 defaults. Always set context length explicitly in the LM Studio model settings — click the gear icon next to the model picker, set “Context Length” to at least 16384 (preferably 32768), and reload the model.²

Named Custom Providers

If you work with multiple custom endpoints (a local dev server and a remote GPU server, for example), define them as named custom providers in config.yaml:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Then switch between them mid-session with the triple syntax:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

You can also select named custom providers from the interactive hermes model menu.²

Context Length Detection

Two settings get confused constantly, per the upstream docs:²

• context_length — the total context window (combined input + output token budget, e.g. 200,000 for Claude Opus 4.6). Hermes uses this to decide when to compress history.
• model.max_tokens — the output cap (max tokens the model may generate in a single response). Unrelated to history length.

Set context_length when auto-detection gets the window size wrong:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes uses a multi-source resolution chain to detect context windows: config override → custom provider per-model → persistent cache → endpoint /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev (community-maintained registry for 3800+ models) → fallback defaults (128K).² The system is provider-aware, so the same model can have different context limits depending on who serves it (e.g., claude-opus-4.6 is 1M on Anthropic direct but 128K on GitHub Copilot).²

Provider Rotation & Fallback

Credential pools. When you have multiple API keys for the same provider, configure a rotation strategy via hermes auth. This is how you distribute rate limits across multiple keys.⁶

Fallback model. Configure a backup provider:model that Hermes switches to automatically when your primary model fails (rate limits, server errors, auth failures):²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

The fallback swaps model and provider mid-session without losing your conversation. It fires at most once per session.² Supported providers for fallback: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Auxiliary Models

Hermes uses lightweight “auxiliary” models for side tasks: image analysis, web page summarization, browser screenshot analysis, dangerous command approval classification, context compression, session search summarization, skill matching, MCP tool dispatch, and memory flush.⁴ By default these use Gemini Flash via auto-detection (OpenRouter → Nous → Codex).

You can configure which model and provider each auxiliary task uses. Every auxiliary slot uses the same three knobs: provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

The "main" provider option means “use whatever provider my main agent uses” — valid only inside auxiliary:, compression:, and fallback_model: configs. It is not valid for your top-level model.provider setting. If you use a custom OpenAI-compatible endpoint as your main model, set provider: custom in your model: section.⁴

Why this matters: if you only configured Anthropic OAuth (no OpenRouter key), your vision, web summarization, and compression will degrade or fail because the default auxiliary fallback chain tries OpenRouter first. Add an OPENROUTER_API_KEY for auxiliary tasks, or reconfigure each auxiliary slot to use your main provider:

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

This is the single most common “my features silently don’t work” gotcha for new Hermes users.

Configuration System

Hermes has a layered configuration system. Understanding the precedence is essential because higher layers override lower ones, and one of the layers is a global provider registry you can’t see in config.yaml.

Config File Layout

Per the upstream docs, these are the files that make up a Hermes configuration:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml vs .env — when both are set, config.yaml wins for non-secret settings.⁴ The rule is: - Secrets (API keys, bot tokens, passwords) → .env - Everything else (model, terminal backend, compression settings, memory limits, toolsets) → config.yaml

Secrets can be referenced from config.yaml using shell-style interpolation:⁴

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

Managing Configuration

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Examples:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check and hermes config migrate are the commands to run after every hermes update — they catch newly added config options that your file doesn’t yet have.⁶

Configuration Precedence

Hermes loads configuration from several sources. When multiple sources set the same value, the higher-priority source wins:⁴

1. CLI arguments — hermes chat --model anthropic/claude-sonnet-4 (per-invocation override)
2. Environment variables — applied at process startup
3. config.yaml — the primary settings file
4. .env — secrets only
5. Built-in defaults — applied when nothing else sets a value

CLI flags always win for that single invocation. config.yaml is the long-term source of truth.

Profiles — Multiple Isolated Hermes Instances

Profiles give you multiple isolated Hermes instances, each with its own config, sessions, skills, memory, and gateway PID. This is how you run “work Hermes” and “personal Hermes” side-by-side without either seeing the other’s state.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Each profile gets its own HERMES_HOME (~/.hermes-<name>/ by default), so multiple profiles can run the gateway concurrently without stepping on each other.⁶³

CLI Commands

This section is the practitioner’s reference to top-level CLI commands. For the authoritative code-derived reference, see the upstream CLI Commands Reference.⁶

Global Options

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

Top-Level Commands

hermes chat — The Main Entry Point

hermes with no arguments drops you into interactive chat. hermes chat is the explicit form with options:⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Key options:

hermes setup — Full Wizard

Runs the full setup wizard or jumps into one section:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — Structured Log Querying

hermes logs is more powerful than tail -f on the log files because it supports filtering by level, session ID, and time range simultaneously.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Log files live in ~/.hermes/logs/:⁶ - agent.log — all agent activity (API calls, tool dispatch, session lifecycle, INFO+) - errors.log — warnings and errors only (a filtered subset of agent.log) - gateway.log — messaging gateway activity (platform connections, dispatch, webhooks)

Rotation is automatic via Python’s RotatingFileHandler — look for agent.log.1, agent.log.2, etc.⁶

hermes doctor — Diagnostics

hermes doctor [--fix] is the first command to run when something is wrong. It checks config validity, dependency presence, API key availability, service status, and can attempt automatic repairs with --fix.⁶

For sharing diagnostics with someone else, use hermes dump — it produces a compact plain-text summary with redacted API keys, ready to paste into a GitHub issue or Discord thread.⁶

Slash Commands

Slash commands run inside an active chat session (CLI or messaging platform). They’re dispatched from a shared COMMAND_REGISTRY in hermes_cli/commands.py, which is why most commands work identically across surfaces.⁹

Session Control

Configuration & Model

The /model command is the workhorse for mid-session provider switching:⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

Tools, Skills & Info

Dynamic Skill Slash Commands

Every installed skill is automatically exposed as a slash command:⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

You can also define quick commands in config.yaml that alias a short name to a longer prompt:⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Then type /review, /deploy, or /morning in the CLI.

Prefix Matching

Commands support prefix matching: typing /h resolves to /help, /mod resolves to /model. When a prefix is ambiguous, the first registration in registry order wins. Full command names and registered aliases always take priority over prefix matches.⁹

Messaging-Specific Commands

Some commands only work on messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant):⁹

• /status — show session info
• /sethome (alias /set-home) — mark the current chat as platform home
• /approve [session|always] — approve a pending dangerous command
• /deny — reject a pending dangerous command
• /update — update Hermes Agent to latest
• /commands [page] — browse all commands and skills (paginated)

And some are CLI-only: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Tools & Toolsets

Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, RL training, messaging delivery, Home Assistant integration, and more.¹⁰ Tools are organized into logical toolsets that can be enabled or disabled per platform.

High-Level Categories

Common toolset names include web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, and rl.¹⁰

Managing Tools

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Tools can also be toggled mid-session via /tools disable <name> and /tools enable <name>, which resets the session so the new tool set takes effect.⁹

Terminal Backends

The terminal tool can execute commands in six different environments:¹⁰

Switch backends with hermes config set terminal.backend <name> or in config.yaml:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

SSH backend (recommended for security — the agent can’t modify its own code):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker backend:

terminal:
  backend: docker
  docker_image: python:3.11-slim

Container resources (applies to docker, singularity, modal, daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

With container_persistent: true, installed packages, files, and config survive across sessions.¹⁰

All container backends run with security hardening: read-only root filesystem (Docker), all Linux capabilities dropped except DAC_OVERRIDE, CHOWN, and FOWNER, no privilege escalation, PID limits (256 processes), full namespace isolation, persistent workspace via volumes.¹⁰

Background Processes

The terminal tool supports background execution with explicit process management:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

PTY mode (pty=true) enables interactive CLI tools like Codex and Claude Code.¹⁰

Sudo

If a command needs sudo, Hermes prompts for your password (cached for the session). Or set SUDO_PASSWORD in ~/.hermes/.env.¹⁰

Skills System

Skills are on-demand knowledge documents the agent can load when needed. They follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard.¹¹

All skills live in ~/.hermes/skills/ — the primary directory and source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here.¹¹

Progressive Disclosure

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

The agent only loads the full skill content when it actually needs it.¹¹

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Conditional Activation

Skills can show or hide themselves based on which tools are available. This is most useful for fallback skills — free or local alternatives that should only appear when a premium tool is unavailable:¹¹

Example: the built-in duckduckgo-search skill uses fallback_for_toolsets: [web]. When you have FIRECRAWL_API_KEY set, the web toolset is available and the agent uses web_search — the DuckDuckGo skill stays hidden. Without the API key, the DuckDuckGo skill automatically appears as a fallback.¹¹

Agent-Managed Skills

The agent can create, update, and delete its own skills via the skill_manage tool. This is the agent’s procedural memory — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.¹¹

When the agent creates skills:¹¹ - After completing a complex task (5+ tool calls) successfully - When it hit errors or dead ends and found the working path - When the user corrected its approach - When it discovered a non-trivial workflow

Actions:¹¹

Skill Hub

Browse, search, install, and manage skills from online registries:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Integrated hub sources:¹¹

Default GitHub taps (browsable without setup): openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

Security Scanning

All hub-installed skills go through a security scanner that checks for data exfiltration, prompt injection, destructive commands, supply-chain signals, and other threats.¹¹

Trust levels:¹¹

--force can override non-dangerous policy blocks for community skills. It does not override a dangerous scan verdict.¹¹

External Skill Directories

You can point Hermes at additional skill directories scanned alongside the local one:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Paths support ~ expansion and ${VAR} environment variable substitution. External directories are read-only — when the agent creates or edits a skill, it always writes to ~/.hermes/skills/. Local precedence wins if a skill name exists in both places.¹¹

Persistent Memory

Hermes has bounded, curated memory that persists across sessions. Two files make up the agent’s memory, both stored in ~/.hermes/memories/:¹²

Both are injected into the system prompt as a frozen snapshot at session start. The agent manages its own memory via the memory tool — add, replace, or remove.¹²

Frozen snapshot pattern: the system prompt injection is captured once at session start and never changes mid-session. This is intentional — it preserves the LLM’s prefix cache for performance. Changes made during a session are persisted to disk immediately but don’t appear in the system prompt until the next session.¹²

What to Save

Save these (the agent does this proactively):¹² - User preferences: “I prefer TypeScript over JavaScript” → user - Environment facts: “This server runs Debian 12 with PostgreSQL 16” → memory - Corrections: “Don’t use sudo for Docker commands, user is in docker group” → memory - Conventions: “Project uses tabs, 120-char line width, Google-style docstrings” → memory - Completed work: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → memory

Skip these:¹² - Trivial/obvious info - Easily re-discovered facts - Raw data dumps (too big for memory) - Session-specific ephemera - Information already in context files

Session Search

Beyond MEMORY.md and USER.md, the agent can search its past conversations using the session_search tool. All CLI and messaging sessions are stored in SQLite (~/.hermes/state.db) with FTS5 full-text search. Queries return relevant past conversations with Gemini Flash summarization.¹²

External Memory Providers

For deeper persistent memory beyond MEMORY.md and USER.md, Hermes ships with eight external memory provider plugins: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, and Supermemory.¹²

External providers run alongside built-in memory (never replacing it) and add capabilities like knowledge graphs, semantic search, automatic fact extraction, and cross-session user modeling:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

Only one external provider can be active at a time. Built-in memory is always active.⁶

Personality & SOUL.md

SOUL.md is the primary identity of a Hermes instance. It occupies slot #1 in the system prompt, replacing the hardcoded default identity.¹³

Hermes seeds a default SOUL.md automatically at ~/.hermes/SOUL.md (or $HERMES_HOME/SOUL.md for custom profiles). Existing user files are never overwritten. Hermes only loads SOUL.md from HERMES_HOME — it does not look in the current working directory. This makes personality predictable across projects.¹³

What Belongs in SOUL.md

Use it for durable voice and personality guidance:¹³ - tone - communication style - level of directness - default interaction style - what to avoid stylistically - how Hermes should handle uncertainty, disagreement, ambiguity

Use it less for:¹³ - one-off project instructions - file paths - repo conventions - temporary workflow details

Those belong in AGENTS.md, not SOUL.md.

SOUL.md vs AGENTS.md

This is the most important distinction in Hermes identity management:¹³

SOUL.md — identity, tone, style, communication defaults, personality-level behavior.

AGENTS.md — project architecture, coding conventions, tool preferences, repo-specific workflows, commands, ports, paths, deployment notes.

A useful rule: if it should follow you everywhere, it belongs in SOUL.md. If it belongs to a project, it belongs in AGENTS.md.¹³

Built-in Personalities

Hermes ships with built-in personalities you can switch to with /personality:¹³

Custom personalities in config.yaml:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Then switch with /personality codereviewer.

SOUL.md vs /personality

SOUL.md is the baseline voice. /personality is a session-level overlay.¹³ Keep a pragmatic default SOUL.md, then use /personality teacher for a tutoring conversation or /personality creative for brainstorming.

Messaging Gateway

Hermes can run as a long-running gateway process that connects to Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), and a generic Webhook adapter — 15+ platform adapters from a single gateway process.³

Setup

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

The interactive setup walks you through connecting each platform: API tokens, bot IDs, channel mappings, allowlists.⁶

How Messages Flow

From the upstream architecture docs:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Every messaging platform runs through the same AIAgent conversation loop as the CLI. That’s why slash commands work identically in both places and why a cron job scheduled in Telegram can deliver its output to Discord — the platform difference is just at the edge.³

User Authorization & Pairing

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Pairing codes prevent random strangers from talking to your gateway. A user sends a pairing code from their messaging platform; you approve it with hermes pairing approve; from then on they’re authorized.⁶

Scheduled Tasks (Cron)

Hermes has a first-class cron system where jobs are agent tasks, not shell commands. Each scheduled job runs through a fresh AIAgent with the configured prompt, optional attached skills, and delivers results to any platform:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

Or create one conversationally inside a messaging chat:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

The agent will set up the cron job via its tools. Jobs persist in JSON and survive restarts.³

MCP Integration

Hermes supports the Model Context Protocol as both a client and a server:⁶

As a client — connect Hermes to external MCP servers to extend its tool surface:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

Or manually in config.yaml:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

As a server — expose Hermes conversations to other agents:

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes automatically compresses long conversations to stay within your model’s context window. The compression summarizer is a separate LLM call — you can point it at any provider or endpoint.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve 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

Provider options:⁴

summary_model must support a context length at least as large as your main model’s, since it receives the full middle section of the conversation for compression.⁴

Budget Pressure Warnings

When the agent works on a complex task with many tool calls, it can burn through its iteration budget (default: 90 turns) without realizing it. Budget pressure automatically warns the model:⁴

Stream Timeouts

The LLM streaming connection has two timeout layers that auto-adjust for local providers (localhost, LAN IPs):⁴

The socket read timeout is raised to 30 minutes for local endpoints because local LLMs can take minutes for prefill on large contexts before producing the first token.⁴

Architecture for Practitioners

This section is for people who want to understand what’s happening under the hood so they can debug it, extend it, or reason about performance. It’s a synthesis of the upstream architecture docs.³

Entry Points → AIAgent

Every entry point in Hermes ultimately calls AIAgent.run_conversation():

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

Diagram adapted from the upstream architecture docs.³

“47 tools / 20 toolsets” vs “28 tools” in your banner. The “47 tools” count is the upstream repository’s total tool registry — every tool Hermes ships with source code for, across every toolset. Your actual running CLI will show a smaller number in its startup banner (the installation I verified this guide against reports 28 tools / 89 skills). That’s not a bug. Many toolsets are opt-in and have to be explicitly enabled in config.yaml under toolsets: — messaging platform adapters, browser automation, heavier scraping tools, etc. The registry total is “what’s available”; the banner number is “what’s enabled in your current profile.” Check which toolsets are active with hermes tools --list and enable or disable individual toolsets with the toolsets: block in ~/.hermes/config.yaml (or /tools list / /tools enable <name> / /tools disable <name> inside a running session — removing a tool triggers a session reset so the agent rebuilds its tool manifest).

The Three API Modes

Hermes abstracts provider differences into three API modes, selected automatically at runtime:³

The runtime_provider.py resolver maps (provider, model) tuples to (api_mode, api_key, base_url) for 18+ providers, handling OAuth flows, credential pools, and alias resolution.³

Data Flow Through a CLI Session

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

From the upstream architecture page.³

Prompt Assembly Order

The prompt stack includes:¹³

1. SOUL.md (agent identity — or built-in fallback if unavailable)
2. Tool-aware behavior guidance
3. Memory/user context (MEMORY.md, USER.md)
4. Skills guidance
5. Context files (AGENTS.md, .cursorrules)
6. Timestamp
7. Platform-specific formatting hints
8. Optional system-prompt overlays such as /personality

SOUL.md is the foundation — everything else builds on top of it.¹³

Session Storage

SQLite-based session storage with FTS5 full-text search. Sessions have lineage tracking (parent/child across compressions), per-platform isolation, and atomic writes with contention handling.³

Plugin System

Three discovery sources: ~/.hermes/plugins/ (user), .hermes/plugins/ (project), and pip entry points. Plugins register tools, hooks, and CLI commands through a context API. Memory providers are a specialized plugin type under plugins/memory/.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

Design Principles

From the upstream architecture page:³

Migration from OpenClaw

Hermes Agent is the successor to OpenClaw. If you’re migrating from an existing OpenClaw installation:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate reads from ~/.openclaw by default (also auto-detects legacy ~/.clawdbot and ~/.moldbot directories) and writes to ~/.hermes.⁶

Directly imported (30+ categories): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills from 4 source directories, default model, custom providers, MCP servers, messaging platform tokens and allowlists (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), agent defaults (reasoning effort, compression, human delay, timezone, sandbox), session reset policies, approval rules, TTS config, browser settings, tool settings, exec timeout, command allowlist, gateway config, and API keys from 3 sources.⁶

Archived for manual review: cron jobs, plugins, hooks/webhooks, memory backend (QMD), skills registry config, UI/identity, logging, multi-agent setup, channel bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

API key resolution checks three sources in priority order: config values → ~/.openclaw/.env → auth-profiles.json.⁶

Troubleshooting

“API key not set”

Run hermes model to configure your provider interactively, or hermes config set OPENROUTER_API_KEY your_key. The hermes doctor command will tell you exactly which keys are missing.⁷

“Context limit: 2048 tokens” at startup (local models)

Hermes auto-detects context length from your server’s /v1/models endpoint, but many local servers report low defaults. Set it explicitly in config.yaml:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Tool calls appear as text instead of executing

Your server doesn’t have tool calling enabled, or the model doesn’t support it through the server’s implementation.²

Responses get cut off mid-sentence

Two possible causes:²

1. Low output cap (max_tokens) on the server — SGLang defaults to 128 tokens per response. Set --default-max-tokens on the server or configure model.max_tokens in config.yaml.
2. Context exhaustion — The model filled its context window. Increase model.context_length or enable context compression in Hermes.

“Connection refused” from WSL2 to a Windows-hosted model server

WSL2 uses a virtual network adapter with its own subnet — localhost inside WSL2 refers to the Linux VM, not the Windows host. Two options:²

Mirrored networking (Windows 11 22H2+): edit %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Then wsl --shutdown and restart. localhost now works bidirectionally.

Host IP fallback (older Windows): get the Windows host IP from inside WSL2 and use it instead of localhost:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

You also need the model server to bind to 0.0.0.0, not 127.0.0.1 — set OLLAMA_HOST=0.0.0.0 for Ollama, add --host 0.0.0.0 for llama-server/SGLang, or enable “Serve on Network” in LM Studio.²

Where is everything?

hermes status and hermes dump are your friends here. hermes logs list shows all log files with sizes. hermes config path prints the config file location. hermes config env-path prints the .env location.⁶

FAQ

What’s the difference between Hermes Agent and Claude Code?

Claude Code is Anthropic’s official CLI, locked to Anthropic models. Hermes Agent is an open-source agent framework from Nous Research that works with any OpenAI-compatible provider — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google, or your own self-hosted endpoint.¹² Hermes also ships a messaging gateway for Telegram/Discord/Slack/WhatsApp/Signal that Claude Code does not have.

Can I use Hermes with an Anthropic API key?

Yes. Three ways:²

1. Set ANTHROPIC_API_KEY in ~/.hermes/.env and run hermes chat --provider anthropic --model claude-sonnet-4-6
2. Run hermes model and select Anthropic — Hermes will use Claude Code’s credential store when available
3. Set a manual ANTHROPIC_TOKEN (setup-token or OAuth token) as a fallback

Option 2 is preferred if you already use Claude Code on the same machine — it keeps refreshable Claude credentials refreshable.

How do I switch providers without losing my conversation?

Use /model provider:model inside a session. The conversation history, memory, and skills all carry over:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

I configured Anthropic but vision/web/compression don’t work

You’re hitting the auxiliary model fallback. Vision, web summarization, compression, and other side tasks use a separate auxiliary LLM — by default Gemini Flash via auto-detection (OpenRouter → Nous → Codex). If none of those are configured and you only have Anthropic set up, these features degrade silently.⁴

Fix: either add an OPENROUTER_API_KEY for auxiliary tasks, or reconfigure auxiliary slots to use your main provider. Note that context compression lives in its own top-level compression: block and takes summary_provider, not auxiliary.compression.provider — the auxiliary.compression slot only exposes a timeout. Full fix:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

What is the difference between SOUL.md and AGENTS.md?

SOUL.md is your agent’s identity — tone, style, communication defaults. It lives in ~/.hermes/SOUL.md and follows you everywhere. AGENTS.md is project-specific — architecture, conventions, commands, paths — and lives in your project directory.¹³ If it should follow you everywhere, SOUL.md. If it belongs to a project, AGENTS.md.

How do I run multiple Hermes instances side-by-side?

Profiles. Each profile gets its own HERMES_HOME, config, memory, sessions, and gateway PID:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Does Hermes support local LLMs?

Yes, through the custom endpoint path. Hermes works with any OpenAI-compatible server: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan, or your own.² See Custom & Self-Hosted Endpoints for per-server setup.

Why does my startup banner show fewer tools than the guide says Hermes has?

The guide cites 47 tools / 20 toolsets from the upstream architecture registry — that’s the full count of tools Hermes ships source code for across every toolset. Your running install shows a smaller number in the banner (the reference install used for this guide reports 28 tools) because Hermes only enables the default toolset set at startup. Many toolsets are opt-in: messaging gateway adapters, browser automation, heavier scraping stacks, and several specialized integrations have to be explicitly listed under toolsets: in ~/.hermes/config.yaml before they load. Registry total = “what’s available if you enable it.” Banner total = “what your current profile actually loaded.” Use hermes tools --list to see which toolsets are active and which are available but disabled. Toggle individual toolsets at runtime with /tools enable <name> and /tools disable <name> (disabling triggers a session reset so the agent rebuilds its tool manifest with the new shape).

How does Hermes handle model fallback when my primary provider fails?

Configure a fallback_model block in config.yaml:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

When the primary fails (rate limit, server error, auth failure), Hermes swaps to the fallback mid-session without losing conversation history. Fires at most once per session.

Can the agent improve its own skills over time?

Yes — that’s the “self-improving” part of Hermes Agent. The agent can create, update, and delete skills via the skill_manage tool. When it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.¹¹ The agent creates skills after complex tasks (5+ tool calls), when it hits errors and finds the working path, when you correct its approach, or when it discovers a non-trivial workflow.

Is there an IDE integration?

Yes — Hermes can run as an ACP (Agent Client Protocol) server for VS Code, Zed, and JetBrains:⁶

pip install -e '.[acp]'
hermes acp

References