Configuration options

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_..."

CLI Reference

Toolsets

Complete example

Model

Agent

Terminal

Browser

Memory

Compression

Display / Skin

Approvals

Tools / Toolsets

Delegation

Auxiliary models

TTS / STT

Checkpoints

Session reset (gateway)

Security

Other

Build docs developers (and LLMs) love

CLI Reference

Toolsets

​Complete example

​Model

​Agent

​Terminal

​Browser

​Memory

​Compression

​Display / Skin

​Approvals

​Tools / Toolsets

​Delegation

​Auxiliary models

​TTS / STT

​Checkpoints

​Session reset (gateway)

​Security

​Other

Build docs developers (and LLMs) love

Complete example

Model

Agent

Terminal

Browser

Memory

Compression

Display / Skin

Approvals

Tools / Toolsets

Delegation

Auxiliary models

TTS / STT

Checkpoints

Session reset (gateway)

Security

Other