Configuration options

Complete reference for all settings in ~/.hermes/config.yaml.

Hermes reads its configuration from ~/.hermes/config.yaml. Missing keys fall back to built-in defaults. The file is created automatically on first run.

# Edit in $EDITOR
hermes config edit

# Set a single value
hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker

# Validate and migrate
hermes config migrate

The current config schema version is 10. Running hermes config migrate adds any new fields introduced since your last update and bumps the _config_version key.

Complete example

model:
  default: "anthropic/claude-opus-4.6"
  provider: "auto"                  # auto | openrouter | nous | zai | kimi-coding | ...
  base_url: "https://openrouter.ai/api/v1"

terminal:
  backend: "local"                  # local | ssh | docker | singularity | modal | daytona
  cwd: "."
  timeout: 180

agent:
  max_turns: 90
  reasoning_effort: "medium"        # none | low | minimal | medium | high | xhigh

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

display:
  skin: "default"                   # default | ares | mono | slate | poseidon | sisyphus | charizard
  tool_progress: "all"              # off | new | all | verbose
  compact: false
  show_reasoning: false
  streaming: false

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

approvals:
  mode: "manual"                    # manual | smart | off

toolsets:
  - all

---

Model

model · string | object · default: "anthropic/claude-opus-4.6"

The default model. Can be a plain string (model slug) or an object with default, provider, and base_url.

# Simple
model: "anthropic/claude-opus-4.6"

# Full object
model:
  default: "anthropic/claude-opus-4.6"
  provider: "openrouter"
  base_url: "https://openrouter.ai/api/v1"

model.provider · string · default: "auto"

Inference provider. Options: auto, openrouter, nous, openai-codex, copilot-acp, copilot, anthropic, zai, kimi-coding, minimax, minimax-cn, kilocode, opencode-zen, opencode-go, ai-gateway, alibaba, custom. Can also be overridden with --provider flag or HERMES_INFERENCE_PROVIDER env var.

model.base_url · string

API base URL. Used to point at custom OpenAI-compatible endpoints.

---

Agent

agent.max_turns · integer · default: "90"

Maximum tool-calling iterations per conversation. Higher values allow more complex tasks at the cost of more tokens. Recommended: 20–30 for focused tasks, 50–100 for open exploration.

agent.reasoning_effort · string

Reasoning effort level for models that support extended thinking (OpenRouter, Nous Portal). Options: xhigh, high, medium, low, minimal, none. Toggle at runtime with /reasoning [level].

---

Terminal

terminal.backend · string · default: "local"

Terminal execution backend. Options:

• local — runs commands on your machine
• ssh — runs commands on a remote server
• docker — isolated Docker container
• singularity — Singularity/Apptainer container (HPC environments)
• modal — Modal cloud sandbox
• daytona — Daytona cloud dev environments

terminal.cwd · string · default: "."

Working directory. For local: . means the directory where hermes was launched. For remote backends, use an absolute path inside the target environment.

terminal.timeout · integer · default: "180"

Default command timeout in seconds.

terminal.persistent_shell · boolean · default: "true"

Keep a long-lived bash shell across execute() calls so cwd, environment variables, and shell state survive between commands. Enabled by default for non-local backends.

terminal.docker_image · string · default: "nikolaik/python-nodejs:python3.11-nodejs20"

Docker image for the docker backend.

terminal.docker_mount_cwd_to_workspace · boolean · default: "false"

Explicitly mount the launch cwd into /workspace inside Docker. Off by default for isolation.

terminal.docker_forward_env · list

List of environment variable names to forward from the host into the Docker container.

terminal:
  docker_forward_env:
    - GITHUB_TOKEN
    - NPM_TOKEN

terminal.docker_volumes · list

Docker volume mounts. Each entry is host_path:container_path (standard Docker -v syntax).

terminal:
  docker_volumes:
    - "/home/user/projects:/workspace/projects"

terminal.container_cpu · integer · default: "1"

CPU cores for container backends (docker, singularity, modal, daytona). Ignored for local and ssh.

terminal.container_memory · integer · default: "5120"

Memory in MB for container backends. Default is 5120 (5 GB).

terminal.container_disk · integer · default: "51200"

Disk space in MB for container backends. Default is 51200 (50 GB).

terminal.container_persistent · boolean · default: "true"

Persist the container filesystem across sessions. Set to false for ephemeral (fresh) containers.

SSH-specific keys (used when backend: ssh):

Key	Description
terminal.ssh_host	SSH hostname or IP
terminal.ssh_user	SSH username
terminal.ssh_port	SSH port (default: 22)
terminal.ssh_key	Path to SSH private key (uses ssh-agent if omitted)

---

Browser

browser.inactivity_timeout · integer · default: "120"

Seconds of agent inactivity before browser sessions are automatically closed.

browser.record_sessions · boolean · default: "false"

Automatically record browser sessions as WebM videos.

---

Memory

memory.memory_enabled · boolean · default: "true"

Enable the agent’s persistent memory store (MEMORY.md). The agent can save facts about the environment, coding conventions, and things it has learned.

memory.user_profile_enabled · boolean · default: "true"

Enable the user profile store (USER.md). The agent saves preferences, communication style, and expectations.

memory.memory_char_limit · integer · default: "2200"

Maximum character count for the agent memory store (~800 tokens at 2.75 chars/token).

memory.user_char_limit · integer · default: "1375"

Maximum character count for the user profile store (~500 tokens).

---

Compression

When a conversation approaches the model’s context limit, middle turns are automatically summarized.

compression.enabled · boolean · default: "true"

Enable automatic context compression.

compression.threshold · number · default: "0.85"

Trigger compression at this fraction of the model’s context limit (e.g. 0.85 = 85%). Lower values compress earlier.

compression.summary_model · string · default: "google/gemini-3-flash-preview"

Fast, cheap model used to generate conversation summaries. Must support a context length at least as large as your main model.

compression.summary_provider · string · default: "auto"

Provider for the summary model. Options: auto, openrouter, nous, main.

---

Display / Skin

display.skin · string · default: "default"

Visual theme for the CLI. Built-in skins: default (gold/kawaii), ares (crimson/bronze), mono (grayscale), slate (blue developer), poseidon (ocean blue), sisyphus (austere grayscale), charizard (volcanic orange). Drop custom YAML skins in ~/.hermes/skins/<name>.yaml and activate with /skin <name>.

display.tool_progress · string · default: "all"

Tool activity display level:

• off — silent, only show the final response
• new — show a tool indicator only when the tool changes
• all — show every tool call with a short preview
• verbose — full args, results, and debug logs

Toggle at runtime with /verbose.

display.compact · boolean · default: "false"

Use compact banner mode.

display.show_reasoning · boolean · default: "false"

Show the model’s reasoning/thinking before each response. Toggle with /reasoning show or /reasoning hide.

display.streaming · boolean · default: "false"

Stream tokens to the terminal as they arrive instead of waiting for the full response.

display.bell_on_complete · boolean · default: "false"

Ring the terminal bell when the agent finishes a response.

display.show_cost · boolean · default: "false"

Show estimated cost in the status bar.

display.personality · string · default: "kawaii"

Default personality preset.

display.background_process_notifications · string · default: "all"

Gateway-only. Controls watcher verbosity for terminal(background=true) calls:

• all — running output + final message
• result — final completion message only
• error — final message only when exit code ≠ 0
• off — no watcher messages

---

Approvals

approvals.mode · string · default: "manual"

Approval mode for dangerous terminal commands:

• manual — always prompt the user
• smart — use an auxiliary LLM to auto-approve low-risk commands, prompt for high-risk
• off — skip all prompts (equivalent to --yolo)

command_allowlist · list · default: "[]"

Permanently allowed dangerous command patterns (added via the “always” approval option during a session).

---

Tools / Toolsets

toolsets · list · default: "[hermes-cli]"

List of toolsets to enable. Use all to enable everything, or specify individual toolset names.

toolsets:
  - all

# or
toolsets:
  - web
  - terminal
  - file

platform_toolsets · object

Per-platform toolset configuration. Keys: cli, telegram, discord, whatsapp, slack, signal, homeassistant.

platform_toolsets:
  cli: [hermes-cli]
  telegram: [web, terminal, file, todo]
  discord: [web, vision, skills]

---

Delegation

delegation.model · string

Model for subagents spawned by delegate_task. Empty inherits the parent’s model.

delegation.provider · string

Provider for subagents. Empty inherits the parent’s provider.

delegation.max_iterations · integer · default: "50"

Maximum tool-calling turns per child agent.

delegation.default_toolsets · list · default: "[terminal, file, web]"

Default toolsets available to subagents.

---

Auxiliary models

Hermes uses lightweight auxiliary models for side tasks (vision analysis, web extraction, context compression, session search). Each task has its own provider + model pair.

auxiliary:
  vision:
    provider: "auto"   # auto | openrouter | nous | codex | main
    model: ""          # e.g. "google/gemini-2.5-flash" (empty = provider default)
  web_extract:
    provider: "auto"
    model: ""
  compression:
    provider: "auto"
    model: ""
  approval:
    provider: "auto"
    model: ""          # fast/cheap model recommended

All tasks fall back to openrouter:google/gemini-3-flash-preview if the configured provider is unavailable.

---

TTS / STT

tts.provider · string · default: "edge"

Text-to-speech provider: edge (free, no API key), elevenlabs (premium), openai, or neutts (local).

stt.provider · string · default: "local"

Speech-to-text provider: local (faster-whisper, no API key), groq, or openai.

stt.enabled · boolean · default: "true"

Enable automatic voice transcription for messaging platforms.

---

Checkpoints

checkpoints.enabled · boolean · default: "true"

Take automatic filesystem snapshots before destructive file operations. Use /rollback to restore.

checkpoints.max_snapshots · integer · default: "50"

Maximum number of checkpoints to keep per directory.

---

Session reset (gateway)

session_reset.mode · string · default: "both"

When to auto-clear messaging sessions: both (idle or daily), idle, daily, or none.

session_reset.idle_minutes · integer · default: "1440"

Inactivity timeout in minutes before a session is reset. Default is 1440 (24 hours).

session_reset.at_hour · integer · default: "4"

Hour of the day (0–23) for the daily reset.

group_sessions_per_user · boolean · default: "true"

In group/channel chats, maintain a separate session per user. Set to false for a single shared context.

---

Security

security.redact_secrets · boolean · default: "true"

Redact API keys, tokens, and passwords from tool output before sending to the LLM.

security.tirith_enabled · boolean · default: "true"

Enable pre-execution command security scanning via tirith (when installed).

privacy.redact_pii · boolean · default: "false"

When true, hash user IDs and strip phone numbers from the LLM context. Names and usernames are not affected.

---

Other

timezone · string · default: ""

IANA timezone string, e.g. America/New_York or Asia/Kolkata. Empty uses server-local time.

prefill_messages_file · string

Path to a JSON file containing ephemeral {role, content} messages injected at every API call for few-shot priming. Never persisted.

honcho · object

Hermes-specific overrides for Honcho integration. Most Honcho config lives in ~/.honcho/config.json (shared with Claude Code, Cursor, etc.).

personalities · object

Custom personality presets. Supports string format ({"name": "system prompt"}) or dict format with description, system_prompt, tone, and style keys.

personalities:
  my-assistant: "You are a helpful assistant focused on Python development."

quick_commands · object

User-defined quick commands that bypass the agent loop entirely (type: exec only).

mcp_servers · object

MCP (Model Context Protocol) server connections. See the MCP documentation for full configuration options.

mcp_servers:
  time:
    command: uvx
    args: ["mcp-server-time"]
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."