08 / config

Agent Configuration

config.yaml is the main Hermes Agent configuration. All behavior, models, tools, platform integrations, and advanced settings are configured here.

The config.yaml file lives at ~/.hermes/config.yaml. Below is an explanation of each section based on the actual config structure.

Model & Provider

Default model

model:
  default: "your-model-name"
  provider: "custom"
  base_url: "https://api.example.com/v1"

default: model used for all conversations. provider: custom if using your own endpoint, or openrouter/openai/anthropic for built-in providers. base_url: API endpoint (only for custom provider).

Custom providers

custom_providers:
  - name: MyProvider
    base_url: "https://api.example.com/v1"
    api_key: "sk-..."
    models:
      my-model-name:
        context_length: 128000

Add custom OpenAI-compatible providers. Each model needs context_length so the agent knows the context window limit. You can add many models from different providers (Groq, Fireworks, Gemini, etc).

Fallback model

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

Auto-failover when primary model is unavailable. Triggers on rate limit (429), overload (529), service error (503), or connection failure. Uncomment to enable.

Agent Behavior

Agent

agent:
  max_turns: 300
  gateway_timeout: 1800
  restart_drain_timeout: 180
  api_max_retries: 3
  tool_use_enforcement: auto
  reasoning_effort: medium
  image_input_mode: auto
  verbose: false

max_turns: max iterations per session. gateway_timeout: total gateway timeout (seconds). restart_drain_timeout: wait time before restart. api_max_retries: retry on API failure. tool_use_enforcement: auto = agent decides when to use tools. reasoning_effort: thinking depth (low/medium/high). image_input_mode: auto = process images if present. verbose: detailed logging.

Personalities

agent:
  personalities:
    helpful: You are a helpful, friendly AI assistant.
    concise: You are a concise assistant. Keep responses brief.
    technical: You are a technical expert.
    creative: You are a creative assistant.
    kawaii: "You are a kawaii assistant! Use cute expressions..."

Define personality presets the agent can use. Each personality is a short system prompt. The agent can switch personality based on context or user request.

Approval Mode

Approvals

approvals:
  mode: yolo
  timeout: 60
  cron_mode: deny
  mcp_reload_confirm: true

mode: yolo = agent executes without asking. smart = agent decides based on risk. always = always asks permission. timeout: seconds before auto-deny. cron_mode: approval control for scheduled tasks. mcp_reload_confirm: ask confirmation when reloading MCP servers.

Terminal & Execution

Terminal

terminal:
  backend: local
  timeout: 180
  persistent_shell: true
  lifetime_seconds: 300
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

backend: local = directly on machine, docker = isolated container. persistent_shell: true = shell stays alive between commands. lifetime_seconds: shell session lifetime. docker_image: image for Docker backend. container_*: resource limits for Docker.

Code execution

code_execution:
  mode: project
  timeout: 300
  max_tool_calls: 50

mode: project = run code in project working directory. timeout: max seconds per execution. max_tool_calls: max tool calls per session.

Browser

browser:
  engine: auto
  cdp_url: ws://localhost:9222
  inactivity_timeout: 120
  command_timeout: 30
  allow_private_urls: true
  record_sessions: true
  dialog_policy: must_respond
  dialog_timeout_s: 300
  camofox:
    managed_persistence: true
  cloud_provider: camofox

engine: auto = pick available (camofox/playwright/cdp). cdp_url: WebSocket endpoint for Chrome DevTools Protocol. allow_private_urls: allow access to private URLs (localhost, intranet). record_sessions: save browser session recordings. dialog_policy: must_respond = agent must respond to browser dialogs. camofox.managed_persistence: Camofox session persistence.

Memory

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 1000000
  user_char_limit: 1000000
  provider: holographic
  nudge_interval: 10
  flush_min_turns: 6

memory_enabled: enable persistent memory. user_profile_enabled: save user profile (preferences, habits). provider: holographic = deep structured memory with entity resolution. nudge_interval: interval for memory save nudges. flush_min_turns: minimum turns before flushing memory to disk.

Delegation (Sub-agent)

Delegation

delegation:
  max_concurrent_children: 3
  max_spawn_depth: 1
  orchestrator_enabled: true
  subagent_auto_approve: true
  inherit_mcp_toolsets: true
  max_iterations: 50
  child_timeout_seconds: 600

max_concurrent_children: max parallel sub-agents. max_spawn_depth: spawn depth (1 = sub-agents can't spawn their own). orchestrator_enabled: allow sub-agents to become orchestrators. subagent_auto_approve: sub-agents run without approval. inherit_mcp_toolsets: sub-agents inherit MCP tools from parent. max_iterations: iteration limit per sub-agent. child_timeout_seconds: timeout per sub-agent.

Platform Messaging

telegram:
  reactions: false
  channel_prompts: {}
  allowed_chats: ""

Telegram auto-detects from TELEGRAM_BOT_TOKEN env var. reactions: allow agent to react to messages. channel_prompts: custom system prompt per channel. allowed_chats: leave empty to allow all, or fill specific chat IDs.

Discord

discord:
  require_mention: true
  auto_thread: true
  reactions: true
  channel_prompts: {}
  allowed_channels: ""

Token in DISCORD_TOKEN env var. require_mention: agent only responds when mentioned. auto_thread: create thread automatically. reactions: allow agent to react to messages. channel_prompts: custom system prompt per channel.

Other platforms

slack:
  require_mention: true
  free_response_channels: ""
  allowed_channels: ""
whatsapp: {}
mattermost:
  require_mention: true
matrix:
  require_mention: true

Hermes supports Slack, WhatsApp, Mattermost, and Matrix. Each platform has similar config: require_mention, allowed_channels, and channel_prompts. Tokens in respective environment variables.

Context Compression

Compression

compression:
  enabled: true
  threshold: 0.2
  target_ratio: 0.2
  protect_last_n: 20
  hygiene_hard_message_limit: 400

enabled: enable context compression. threshold: 0.2 = start compressing when context is 80% full. target_ratio: 0.2 = compress down to 20% usage. protect_last_n: last 20 messages are never compressed. hygiene_hard_message_limit: message limit before hard compression.

Auxiliary (Additional Models)

The auxiliary section configures additional models for specific tasks: vision, web extraction, compression, session search, etc. Can use different models from the main model.

Auxiliary

auxiliary:
  vision:
    provider: custom:myprovider
    model: your-vision-model
    timeout: 120
  web_extract:
    provider: auto
    timeout: 360
  compression:
    provider: auto
    timeout: 120
  session_search:
    provider: auto
    timeout: 30
    max_concurrency: 3

vision: model for image analysis. web_extract: model for web content extraction. compression: model for context compression. session_search: model for session history search. provider: auto = use default model, or specify provider:model.

Skills

skills:
  external_dirs: []
  template_vars: true
  inline_shell: false
  inline_shell_timeout: 10
  guard_agent_created: false
  creation_nudge_interval: 15
  disabled:
    - airtable
    - notion
    - obsidian
    - codex

external_dirs: additional custom skill directories. template_vars: enable template variables in skills. inline_shell: allow direct shell commands in skills. disabled: disable unused skills to save context window.

Display & Appearance

Display

display:
  compact: false
  personality: kawaii
  streaming: true
  language: en
  inline_diffs: true
  show_cost: false
  skin: default
  bell_on_complete: false
  show_reasoning: false

compact: more compact display. personality: active personality (must exist in agent.personalities). streaming: show response streaming. language: UI language. inline_diffs: show diff when editing files. show_cost: show cost per request. skin: visual theme.

Security

Security & Privacy

security:
  allow_private_urls: true
  redact_secrets: true
  tirith_enabled: true
  tirith_timeout: 5
  tirith_fail_open: true
privacy:
  redact_pii: true

allow_private_urls: allow access to private URLs (localhost, 192.168.x.x). redact_secrets: automatically hide API keys and secrets in output. tirith_enabled: enable security scanning (Tirith). privacy.redact_pii: hide personal data.

Voice (TTS/STT)

TTS & STT

tts:
  provider: edge
  edge:
    voice: en-US-AriaNeural
stt:
  enabled: true
  provider: local
  local:
    model: base

TTS: text-to-speech. Provider: edge (free), elevenlabs, openai, xai, mistral, piper. STT: speech-to-text. Provider: local (whisper), openai, mistral. voice.record_key: shortcut to start recording (default: ctrl+b).

Other Settings

Scheduling & Cron

cron:
  wrap_response: true
  max_parallel_jobs: null
kanban:
  dispatch_in_gateway: true
  dispatch_interval_seconds: 60
  failure_limit: 2

cron: scheduled tasks settings. wrap_response: wrap output with metadata. max_parallel_jobs: null = unlimited. kanban: internal task board system. dispatch_in_gateway: dispatch tasks from gateway. dispatch_interval_seconds: interval for checking new tasks.

Sessions & Logging

sessions:
  auto_prune: false
  retention_days: 90
logging:
  level: INFO
  max_size_mb: 5
  backup_count: 3

sessions: auto_prune = automatically delete old sessions. retention_days: how many days to keep sessions. logging.level: INFO/DEBUG/WARNING/ERROR. max_size_mb: log file size limit.

Minimal Config Example

Below is a minimal config example for an autonomous agent. Adjust model, provider, and platform to your needs.

model:
  default: "your-model-name"
  provider: "custom"
  base_url: "https://api.example.com/v1"

agent:
  max_turns: 300
  tool_use_enforcement: auto
  reasoning_effort: medium

approvals:
  mode: yolo
  cron_mode: deny

terminal:
  backend: local
  timeout: 180
  persistent_shell: true

browser:
  engine: auto

memory:
  memory_enabled: true
  user_profile_enabled: true

delegation:
  max_concurrent_children: 3
  orchestrator_enabled: true
  subagent_auto_approve: true

compression:
  enabled: true

telegram:
  reactions: false

This config gives the agent full autonomy: custom model, yolo approval, local terminal, auto-detect browser, active memory, and auto-approved sub-agents. Just add platform credentials in .env.

Never commit config.yaml to a public repository — this file can contain API keys and credentials. Always use .env for secrets. Config version (_config_version) is auto-updated by Hermes when format changes.

← About Waguri

Hermes SOUL Guide — building a smart agent is a process, not an instant prompt.