Hermes Agent: Configuration Files

Q: Where is the config file?

Default location is ~/.hermes/config.yaml . Change via HERMES_CONFIG_PATH environment variable.

Q: How to backup config?

hermes config export > backup.yaml , or directly copy ~/.hermes/config.yaml .

Q: How to reset to defaults?

hermes config reset , or delete config.yaml and re-run hermes init .

Last updated: 2026-08-31

Configuration files are the brain control center of Hermes Agent — with the right settings, the Agent feels like an old friend who understands you; with wrong ones, it's like a new hire who doesn't know the ropes.

💡 Tip: Hermes uses YAML as its primary configuration format, supports environment variable overrides, and multi-environment switching. All settings have sensible defaults — zero-config startup works out of the box.

📋 Prerequisites: Lesson 2 — Installation

1. What You Will Learn

#	Content
❶	config.yaml complete structure
❷	Core configuration options explained
❸	Environment variable override mechanism
❹	Multi-environment configuration management
❺	Configuration validation and debugging

2. Story

(1) Pain Point: Config Changes Every Time You Switch Environments

Bob uses local models during development, switches to cloud API for deployment, and needs a different Key for testing. Every time he manually edits config files, often making mistakes or forgetting to switch back.

(2) Solution: Environment Configuration Separation

Alice solved this with environment variables and multiple config files:

BASH

# Development environment
hermes chat --env dev

# Production environment
hermes chat --env prod

# Test environment
hermes chat --env test

Bob never has to manually edit configs again.

3. config.yaml Complete Structure

YAML

# ~/.hermes/config.yaml

# ===== Agent Basic Config =====
agent:
  name: "MyHermes"
  version: "1.0.0"
  description: "My personal AI assistant"
  
  personality:
    tone: "friendly"
    verbosity: "balanced"
    language: "en"

  memory:
    enabled: true
    working_memory_limit: 50
    long_term_auto_save: true
    user_model_update: true
    honcho_endpoint: null

# ===== Model Config =====
model:
  default: "gpt-4o"
  fallback: "gpt-4o-mini"
  temperature: 0.7
  max_tokens: 4096
  timeout: 60

# ===== Skills Config =====
skills:
  auto_learn: true
  learn_threshold: 3
  custom_skills_dir: null

# ===== Tools Config =====
tools:
  enabled_categories:
    - filesystem
    - web
    - code_execution
    - vision
    - voice
    - data
  disabled_tools: []
  sandbox: true
  max_execution_time: 30

# ===== Platform Config =====
platforms:
  telegram:
    enabled: false
    token: null
  discord:
    enabled: false
    token: null
  slack:
    enabled: false
    token: null
  web:
    enabled: true
    port: 8080
  terminal:
    enabled: true

# ===== Security & Privacy =====
security:
  redact_api_keys: true
  sandbox_code: true
  allowed_paths:
    - "~/projects"
    - "~/documents"
  denied_paths:
    - "~/.ssh"
    - "~/.gnupg"

# ===== Logging =====
logging:
  level: "INFO"
  file: "~/.hermes/logs/hermes.log"
  max_size_mb: 100
  rotation: 7

# ===== Advanced =====
advanced:
  cron_enabled: true
  checkpoint_enabled: true
  delegate_enabled: true
  mcp_enabled: true
  research_mode: false

4. Core Configuration Options

(1) Agent Personality

YAML

personality:
  tone: "friendly"
  verbosity: "balanced"
  language: "en"
  custom_prompt: |
    You are my technical assistant, skilled in:
    1. React + TypeScript development
    2. Code review and optimization
    3. Technical documentation
    Respond in concise English.

(2) Memory Configuration

YAML

memory:
  working_memory_limit: 50
  long_term_auto_save: true
  user_model_update: true
  recall_on_start: true
  memory_decay: false

(3) Tool Security Boundaries

YAML

tools:
  sandbox: true
  max_execution_time: 30
  
  filesystem:
    allow_write: true
    allow_delete: false
    max_file_size: 10MB
    
  web:
    allow_requests: true
    blocked_domains:
      - "malware-site.com"
    rate_limit: 10

5. Environment Variable Override

Any config option can be overridden via environment variables. Rule: HERMES_ prefix + underscore-separated path.

BASH

# Override default model
export HERMES_MODEL_DEFAULT="gpt-4o-mini"

# Override API Key
export OPENAI_API_KEY="sk-..."

# Override memory settings
export HERMES_MEMORY_ENABLED="false"

# Override log level
export HERMES_LOGGING_LEVEL="DEBUG"

# Use .env file (recommended)
cat > ~/.hermes/.env << EOF
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
HERMES_MODEL_DEFAULT=gpt-4o
HERMES_LOGGING_LEVEL=INFO
EOF

Priority Order

CLI arguments > Environment variables > .env file > config.yaml > Defaults

6. Multi-Environment Management

BASH

# Directory structure
~/.hermes/
├── config.yaml           # Default config
├── config.dev.yaml       # Development
├── config.prod.yaml      # Production
├── config.test.yaml      # Testing
└── .env                  # Environment variables

YAML

# config.dev.yaml - Development
model:
  default: "llama3.2"
  temperature: 0.9

logging:
  level: "DEBUG"

tools:
  sandbox: false

YAML

# config.prod.yaml - Production
model:
  default: "gpt-4o"
  temperature: 0.5

logging:
  level: "WARNING"

security:
  sandbox_code: true
  redact_api_keys: true

7. Configuration Validation

BASH

# Validate config file
hermes config validate

# Show effective config
hermes config show

# Get specific config value
hermes config get model.default

# Set config value
hermes config set model.temperature 0.5

# Export config
hermes config export > backup.yaml

Try It: Customize Your Agent

BASH

hermes config set personality.tone "professional"
hermes config set personality.language "en"
hermes config set memory.working_memory_limit 100

hermes config show | head -20

hermes chat
> Hello! Your tone setting has been switched to professional mode.

❓ FAQ

Q Where is the config file?

A Default location is ~/.hermes/config.yaml. Change via HERMES_CONFIG_PATH environment variable.

Q Do I need to restart after changing config?

A Most configs hot-reload without restart. Model switching and platform configs require restart.

Q What happens if config is wrong?

A Hermes validates config on startup, reports errors with line numbers, and won't silently use incorrect settings.

Q How to backup config?

A hermes config export > backup.yaml, or directly copy ~/.hermes/config.yaml.

Q Share config across machines?

A Put config files in a Git repo, clone on each machine, and set HERMES_CONFIG_PATH to point to the repo config. Never commit API Keys!

Q How to reset to defaults?

A hermes config reset, or delete config.yaml and re-run hermes init.

📖 Summary

config.yaml is the main config file covering Agent, models, memory, tools, platforms, etc.
Priority: CLI args > env vars > .env > config.yaml > defaults
Multi-environment: config.dev.yaml / config.prod.yaml for dev/prod switching
hermes config validate to check config, hermes config show to view effective values
Security: sandbox, path restrictions, API key redaction

📝 Exercises

Basic (⭐): Modify config.yaml to set your Agent name and language preference, verify it takes effect.
Intermediate (⭐⭐): Create dev and prod config sets, implement one-click environment switching.
Advanced (⭐⭐⭐): Design a 12-factor configuration scheme using environment variables, ensuring zero hardcoded secrets.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us

Hermes Agent: Configuration Files

1. What You Will Learn

2. Story

(1) Pain Point: Config Changes Every Time You Switch Environments

(2) Solution: Environment Configuration Separation

3. config.yaml Complete Structure

4. Core Configuration Options

(1) Agent Personality

(2) Memory Configuration

(3) Tool Security Boundaries

5. Environment Variable Override

Priority Order

6. Multi-Environment Management

7. Configuration Validation

Try It: Customize Your Agent

❓ FAQ

📖 Summary

📝 Exercises

🙏 帮我们做得更好