TutorialsGuidesBlogLearning Path

Understanding Hermes Agent Configuration: A Beginner's Guide

🟒 Beginner⏱ 11 min readπŸ“… 2026-04-14πŸ‘€ HermesAgent Community

Configuration Overview

Hermes Agent is highly customizable. Every aspect of its behavior β€” from which AI model it uses to how it handles file permissions β€” can be configured through a simple YAML file, environment variables, or CLI flags.

After installing Hermes, a default configuration file is created at:

~/.hermes/config.yaml

You can edit this file directly, or use the hermes config command for quick changes.

The Configuration File

Here's a complete annotated configuration file with all available options:

# ~/.hermes/config.yaml

# Hermes Agent Configuration


# Documentation: https://hermesagent.sbs/en/tutorials/getting-started/configuration-guide



# ═══════════════════════════════════════════


# API & Model Settings


# ═══════════════════════════════════════════



# Your API key (supports OpenRouter, OpenAI, Anthropic)


api_key: sk-or-v1-your-key-here



# Default AI model


default_model: anthropic/claude-3.5-sonnet



# API provider: openrouter | openai | anthropic | ollama | custom


provider: openrouter



# Custom API base URL (for self-hosted or compatible APIs)


# api_base: http://localhost:11434/v1



# Model parameters


temperature: 0.7         # 0.0 = deterministic, 1.0 = creative


max_tokens: 4096          # Maximum response length


top_p: 1.0                # Nucleus sampling


frequency_penalty: 0.0    # Reduce repetition



# Model aliases for quick switching


model_aliases:


  fast: openai/gpt-4o-mini


  smart: anthropic/claude-3.5-sonnet


  code: anthropic/claude-3.5-sonnet


  cheap: openai/gpt-4o-mini


  local: ollama/llama3.1:8b



# ═══════════════════════════════════════════


# Behavior Settings


# ═══════════════════════════════════════════



# Auto-confirm destructive actions (file writes, deletes)


# WARNING: Set to true only if you trust the model completely


auto_confirm: false



# Show thinking/reasoning blocks


show_thinking: true



# Show tool call details


show_tool_calls: true



# Verbose logging


verbose: false



# Terminal color theme: dark | light | none


theme: dark



# Maximum number of retries on API errors


max_retries: 3



# Timeout for API calls (seconds)


timeout: 120



# ═══════════════════════════════════════════


# Session Settings


# ═══════════════════════════════════════════



# Where to store session data


session_dir: ~/.hermes/sessions



# Maximum messages to keep in context


max_context_messages: 50



# Maximum total tokens in context


max_context_tokens: 100000



# Auto-save sessions


auto_save: true



# Default session name


default_session: default



# ═══════════════════════════════════════════


# Memory Settings


# ═══════════════════════════════════════════



# Enable long-term memory


memory_enabled: true



# Memory storage directory


memory_dir: ~/.hermes/memory



# Maximum number of memories to include in context


max_memory_items: 20



# ═══════════════════════════════════════════


# File System Permissions


# ═══════════════════════════════════════════



# Directories Hermes is allowed to read/write


# Use "~" for home directory, "." for current directory


allowed_paths:


  - "."


  - "~/projects"


  - "~/Documents"



# Directories Hermes is NEVER allowed to access


blocked_paths:


  - "~/.ssh"


  - "~/.gnupg"


  - "/etc"


  - "/var"



# File operations that require confirmation


confirm_operations:


  - delete


  - overwrite


  - move



# ═══════════════════════════════════════════


# Skills Settings


# ═══════════════════════════════════════════



# Skills directory


skills_dir: ~/.hermes/skills



# Auto-load skills on startup


auto_load_skills: true



# Skills to always load


default_skills:


  - web-search


  - file-manager


  - code-runner



# ═══════════════════════════════════════════


# Messaging Integration


# ═══════════════════════════════════════════



# Telegram bot configuration


telegram:


  enabled: false


  bot_token: ""


  allowed_users: []     # Telegram user IDs



# Discord bot configuration


discord:


  enabled: false


  bot_token: ""


  allowed_channels: []



# ═══════════════════════════════════════════


# Cron / Scheduled Tasks


# ═══════════════════════════════════════════



cron:


  enabled: false


  tasks_dir: ~/.hermes/cron


  log_dir: ~/.hermes/cron/logs

Using the Config CLI

The hermes config command provides a convenient interface:

# View all settings

hermes config list



# View a specific setting


hermes config get default_model


# Output: anthropic/claude-3.5-sonnet



# Change a setting


hermes config set default_model openai/gpt-4o



# Reset a setting to default


hermes config unset temperature



# Reset everything


hermes config reset



# Open config file in your editor


hermes config edit

Nested Values

For nested configuration, use dot notation:

# Set Telegram bot token

hermes config set telegram.bot_token "123456:ABC-DEF"



# Enable Telegram


hermes config set telegram.enabled true



# Add an allowed path


hermes config append allowed_paths "~/work"

Environment Variables

Every configuration option can be overridden with environment variables. The format is HERMES_ followed by the uppercase config key:

export HERMES_API_KEY=sk-or-v1-your-key

export HERMES_DEFAULT_MODEL=anthropic/claude-3.5-sonnet


export HERMES_PROVIDER=openrouter


export HERMES_TEMPERATURE=0.5


export HERMES_VERBOSE=true


export HERMES_AUTO_CONFIRM=false

Priority Order

Configuration is resolved in this order (highest priority first):

  • CLI flags β€” hermes --model gpt-4o
  • Environment variables β€” HERMES_DEFAULT_MODEL=gpt-4o
  • Config file β€” ~/.hermes/config.yaml
  • Defaults β€” Built-in default values

    • This means CLI flags always win, making it easy to override settings for specific tasks:

    # Use a different model just for this command

    hermes --model openai/gpt-4o-mini "Quick question: what is 2+2?"
    


    # Normally this config option is false, but override for bulk operations
    

    hermes --no-confirm -f "src/*/.ts" "Add JSDoc comments to all exports"

    Configuration Profiles

    For different workflows, create multiple config profiles:

    # Create a "work" profile

    cp ~/.hermes/config.yaml ~/.hermes/config.work.yaml
    


    # Create a "personal" profile
    

    cp ~/.hermes/config.yaml ~/.hermes/config.personal.yaml

    Switch between profiles:

    # Use the work profile

    HERMES_CONFIG=~/.hermes/config.work.yaml hermes
    


    # Or create aliases in your .bashrc
    

    alias hermes-work="HERMES_CONFIG=~/.hermes/config.work.yaml hermes"
    

    alias hermes-personal="HERMES_CONFIG=~/.hermes/config.personal.yaml hermes"

    Security Best Practices

    Protect Your API Key

    Never commit your API key to version control:

    # Add to .gitignore

    echo ".env" >> .gitignore
    

    echo ".hermes/" >> .gitignore

    Use environment variables for API keys instead of the config file:

    # In .bashrc or .zshrc

    export HERMES_API_KEY=sk-or-v1-your-key

    Restrict File Access

    Configure allowed_paths to limit where Hermes can read and write. This prevents accidental modification of system files or sensitive directories:

    allowed_paths:

      - "~/projects"           # Only your projects directory
    

      - "/tmp/hermes-scratch"  # Temp directory for experiments
    


    blocked_paths:
    

      - "~/.ssh"               # SSH keys
    

      - "~/.gnupg"             # GPG keys
    

      - "~/.hermes/config.yaml" # Prevent self-modification
    

      - "~/passwords.txt"      # Sensitive files

    Use Confirmation Prompts

    Keep auto_confirm: false (the default) so Hermes always asks before:

    • Writing or overwriting files
    • Deleting files
    • Running shell commands
    • Making external API calls

    auto_confirm: false

    confirm_operations:
    

      - delete
    

      - overwrite
    

      - move
    

      - execute      # Shell commands
    

      - network       # External API calls

    Audit Logging

    Enable detailed logging for sensitive environments:

    verbose: true

    log_file: ~/.hermes/audit.log
    

    log_level: info  # debug | info | warn | error

    Tuning Model Parameters

    Temperature

    Controls randomness in responses:

    # Deterministic (exact, reproducible)

    temperature: 0.0
    


    # Balanced (good default)
    

    temperature: 0.7
    


    # Creative (more varied, less predictable)
    

    temperature: 1.0

    Recommendation: Use 0.0-0.3 for code generation and 0.5-0.8 for creative writing.

    Max Tokens

    Controls the maximum response length:

    # Short responses (quick questions)

    max_tokens: 1024
    


    # Medium responses (general use)
    

    max_tokens: 4096
    


    # Long responses (full file generation)
    

    max_tokens: 8192

    Context Window Management

    If you're running into context limits, adjust these:

    max_context_messages: 30    # Fewer messages = less context used

    max_context_tokens: 50000   # Hard limit on context size

    Validating Your Configuration

    Run the built-in validator to check for errors:

    hermes config validate


    βœ… API key: Valid

    βœ… Provider: openrouter
    

    βœ… Default model: anthropic/claude-3.5-sonnet (available)
    

    βœ… Session directory: ~/.hermes/sessions (writable)
    

    βœ… Memory directory: ~/.hermes/memory (writable)
    

    ⚠️ Telegram: Disabled
    

    ⚠️ Discord: Disabled
    

    βœ… Configuration is valid!

    Next Steps

    With your configuration dialed in, continue with:

    Last updated: April 15, 2026 Β· Hermes Agent v0.8
    ← Back to TutorialsTutorial Index