Skip to main content

​
Config files

Hermes stores all configuration in ~/.hermes/:
FilePurpose
~/.hermes/config.yamlAll settings — model, terminal, display, memory, tools
~/.hermes/.envAPI keys and secrets (mode 0600, never committed)
The .env file is created at setup and secured with owner-only permissions. Never put API keys directly in config.yaml.

​
Managing config

hermes config set key value      # Set a single value (dot-notation for nested)
hermes config edit               # Open config.yaml in your $EDITOR
hermes setup                     # Re-run the full interactive setup wizard
You can also change many settings in-session with slash commands: 
/model anthropic/claude-opus-4.6   # Change model
/config                            # Show current configuration
/skin slate                        # Change theme
/verbose                           # Cycle tool progress level

​
Model and provider selection

Select your model interactively: 
hermes model
Or set it directly: 
hermes config set model anthropic/claude-opus-4.6
In-session: 
/model openrouter:google/gemini-3-flash-preview
/model nous:hermes-3-llama-3.1-405b

​
Supported providers

The official Nous Research model portal. Authenticate via OAuth:
hermes login
# or: hermes model → select "Nous Portal"
The OAuth flow opens your browser for authentication and stores credentials locally in ~/.hermes/auth.json. No API key needed — Hermes handles credential refresh automatically.

​
Other supported providers

ProviderKey(s)
Z.AI / GLMGLM_API_KEY
Kimi / MoonshotKIMI_API_KEY
MiniMaxMINIMAX_API_KEY
DeepSeekDEEPSEEK_API_KEY
Alibaba DashScope (Qwen)DASHSCOPE_API_KEY
OpenCode ZenOPENCODE_ZEN_API_KEY
OpenCode GoOPENCODE_GO_API_KEY

​
config.yaml reference

Below is a representative ~/.hermes/config.yaml with the most commonly tuned options: 
# Model
model: "anthropic/claude-opus-4.6"

# Agent behavior
agent:
  max_turns: 90          # Max tool-calling iterations per turn
  reasoning_effort: "medium"  # none | low | minimal | medium | high | xhigh

# Terminal backend
terminal:
  backend: "local"       # local | docker | ssh | modal | daytona | singularity
  cwd: "."               # Working directory (. = current dir for CLI)
  timeout: 180

# Context compression
compression:
  enabled: true
  threshold: 0.50        # Compress at 50% context usage
  summary_model: "google/gemini-3-flash-preview"

# Display
display:
  skin: "default"        # default | ares | mono | slate | poseidon | sisyphus | charizard
  show_reasoning: false
  streaming: false
  compact: false

# Memory
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  nudge_interval: 10
  flush_min_turns: 6

# Approval mode for dangerous commands
approvals:
  mode: "manual"         # manual | smart | off

​
Configuration sections

model: "anthropic/claude-opus-4.6"

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

# Fallback provider if primary is rate-limited or unavailable
# fallback_model:
#   provider: openrouter
#   model: anthropic/claude-sonnet-4

# Route short messages to a cheaper model
smart_model_routing:
  enabled: false
  max_simple_chars: 160
  max_simple_words: 28
  cheap_model:
    provider: openrouter
    model: google/gemini-2.5-flash

​
Environment variables vs config.yaml

Hermes uses two distinct systems:
  • ~/.hermes/.env — API keys, tokens, and passwords. Never exposed to the agent. Loaded on startup and overrides stale shell exports.
  • ~/.hermes/config.yaml — All behavioral settings. The authoritative source for model, terminal, display, and memory configuration.
When both set the same value, config.yaml wins for terminal settings; .env wins for API keys.
Use hermes config set key value with dot notation to set nested values without manually editing YAML:
hermes config set terminal.backend docker
hermes config set display.skin slate
hermes config set compression.threshold 0.75

​
Config version migration

Hermes uses a _config_version field in config.yaml (currently 10) to track schema changes. When you update Hermes, it automatically:
  1. Detects that your config is on an older version
  2. Merges any new default fields into your config
  3. Prompts for any new optional API keys that were added
  4. Bumps _config_version to the latest value
You can trigger migration manually: 
hermes setup
No existing config values are overwritten during migration — only missing keys are added.

Build docs developers (and LLMs) love

Get started for freeTalk to us