**Duration:** ~45 minutes reading
**Prerequisites:** Module 1 (Installation) & Module 2 (Quickstart)
**Goal:** Master every configuration mechanism in Hermes Agent — from API keys to credential pools to security profiles.
3.1 Where Config Lives
Hermes Agent keeps all configuration in two files under `~/.hermes/` (or wherever `$HERMES_HOME` points):
| File | Purpose | Security Level |
|---|---|---|
| `~/.hermes/config.yaml` | Behavioral settings, model preferences, tool config, display options | Safe to share; no secrets |
| `~/.hermes/.env` | API keys and sensitive credentials | **Never share** — treat like SSH keys |
This split means you can version-control your `config.yaml` or share it between machines without accidentally leaking API keys.
The Config Hierarchy
Hermes loads settings in this order (last wins):
1. **Hardcoded defaults** — built into the CLI
2. **`~/.hermes/config.yaml`** — your personal overrides
3. **`./cli-config.yaml`** — project-level config, useful for team repos
4. **Environment variables** — override everything at runtime (e.g., `HERMES_YOLO_MODE=1`)
Environment variables are documented at [hermes-agent.nousresearch.com/docs/reference/environment-variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables).
Editing Your Config
You have two options:
# Quick method — opens in your $EDITOR
hermes config edit
# Programmatic method — set individual values
hermes config set model.default "openrouter/anthropic/claude-sonnet-4-20250514"
hermes config set agent.max_turns 120
# View current config (merged from all sources)
hermes config
Manual YAML editing (`vim ~/.hermes/config.yaml`) gives you the most control and is perfectly safe — the parser is lenient and validates on load.
3.2 Model Provider Setup
Hermes supports every major LLM provider through a unified plugin system. Each provider is a separate plugin under `plugins/model-providers/`.
Provider Comparison Table
| Provider | Plugin Name | Auth Method | Env Var(s) | API Docs |
|---|---|---|---|---|
| **OpenRouter** | `openrouter` | API key | `OPENROUTER_API_KEY` | [openrouter.ai/keys](https://openrouter.ai/keys) |
| **Anthropic** | `anthropic` | API key, OAuth | `ANTHROPIC_API_KEY`, `ANTHROPIC_TOKEN` | [console.anthropic.com](https://console.anthropic.com) |
| **OpenAI (Chat)** | (built-in) | API key | `OPENAI_API_KEY` | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
| **OpenAI Codex** | `openai-codex` | OAuth (Plus/Pro) | (none — OAuth flow) | Requires ChatGPT Plus/Pro |
| **DeepSeek** | `deepseek` | API key | `DEEPSEEK_API_KEY` | [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) |
| **Google Gemini** | `gemini` | API key (AI Studio) | `GOOGLE_API_KEY`, `GEMINI_API_KEY` | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
| **Nous (Portal)** | `nous` | OAuth or API key | `NOUS_API_KEY` | [portal.nousresearch.com](https://portal.nousresearch.com) |
| **xAI** | `xai` | API key | `XAI_API_KEY` | [console.x.ai](https://console.x.ai) |
| **Z.AI (GLM)** | `zai` | API key | `ZHIPUAI_API_KEY` | [open.bigmodel.cn](https://open.bigmodel.cn) |
| **AWS Bedrock** | `bedrock` | IAM credentials | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` | [aws.amazon.com/bedrock](https://aws.amazon.com/bedrock) |
| **Hugging Face** | `huggingface` | API key | `HUGGINGFACE_API_KEY` | [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) |
| **NovitaAI** | `novita` | API key | `NOVITA_API_KEY` | [novita.ai](https://novita.ai) |
| **NVIDIA NIM** | `nvidia` | API key | `NVIDIA_API_KEY` | [build.nvidia.com](https://build.nvidia.com) |
| **Ollama (Cloud)** | `ollama-cloud` | API key | `OLLAMA_API_KEY` | [ollama.cloud](https://ollama.cloud) |
| **Alibaba** | `alibaba` | API key | `ALIBABA_API_KEY` | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) |
| **Kimi/Moonshot** | `kimi-coding` | API key | `MOONSHOT_API_KEY` | [platform.moonshot.cn](https://platform.moonshot.cn) |
| **MiniMax** | `minimax` | API key | `MINIMAX_API_KEY` | [platform.minimaxi.com](https://platform.minimaxi.com) |
| **Xiaomi MiMo** | `xiaomi` | API key | `MIMO_API_KEY` | [platform.xiaomimimo.com](https://platform.xiaomimimo.com) |
| **Stepfun** | `stepfun` | API key | `STEPFUN_API_KEY` | [stepfun.com](https://stepfun.com) |
| **Arcee** | `arcee` | API key | `ARCEE_API_KEY` | [arcee.ai](https://arcee.ai) |
| **Vercel AI Gateway** | `ai-gateway` | API key | `AI_GATEWAY_API_KEY` | [vercel.com/ai-gateway](https://vercel.com/ai-gateway) |
| **Custom (any)** | `custom` | API key | `OPENAI_API_KEY` + set `base_url` | Your own endpoint |
Quick Setup: OpenRouter (Recommended Starting Point)
OpenRouter is the easiest way to start — 200+ models with a single API key.
1. Go to [openrouter.ai/keys](https://openrouter.ai/keys) and create a key
2. Add it to `~/.hermes/.env`:
```bash
OPENROUTER_API_KEY=sk-or-v1-your-key-here
```
3. Run `hermes model` and select OpenRouter → any model you like
Setting Up Other Providers
**Anthropic / Claude:**
# In ~/.hermes/.env:
ANTHROPIC_API_KEY=sk-ant-your-key-here
Then `hermes model` → pick Claude Sonnet 4 or Haiku 3.5.
**OpenAI:**
# In ~/.hermes/.env:
OPENAI_API_KEY=sk-proj-your-key-here
Then `hermes model` → pick GPT-4o or o3-mini.
**DeepSeek:**
# In ~/.hermes/.env:
DEEPSEEK_API_KEY=sk-your-key-here
Then `hermes model` → pick `deepseek/deepseek-chat-v3-0324`.
**Google Gemini:**
# In ~/.hermes/.env:
GOOGLE_API_KEY=AIza-your-key-here
Then `hermes model` → pick `gemini/gemini-3-flash-preview`.
**Local Models (via Custom Provider):**
# In ~/.hermes/.env (if auth needed):
OPENAI_API_KEY=lm-studio
# Or set OPENAI_API_KEY=not-needed for unauthenticated endpoints
# In ~/.hermes/config.yaml:
model:
default: "local-model-name"
provider: "custom"
base_url: "http://localhost:1234/v1" # LM Studio, Ollama, vLLM, etc.
The `hermes model` Command
The fastest way to configure a provider is the interactive model picker:
hermes model
This presents a paginated, searchable list of all models from all configured providers. It detects which API keys you have set and only shows providers with valid credentials.
You can also set the model programmatically:
hermes model "openrouter/anthropic/claude-sonnet-4-20250514"
hermes model "gpt-4o" --provider openai
3.3 Credential Pools
A credential pool lets you register **multiple API keys for the same provider** for automatic failover or load balancing. This is essential for production use where rate limits or quota exhaustion can interrupt work.
Pool Strategies
| Strategy | Behavior | Best For |
|---|---|---|
| `fill_first` | Use first key until exhausted, then rotate | Simple redundancy |
| `round_robin` | Cycle through keys evenly | Load balancing multiple keys |
| `random` | Pick a random key each time | Spreading usage across plans |
| `least_used` | Track API call counts per key, use the least-loaded | Maximizing remaining quota |
Managing Credential Pools
# Interactive pool management
hermes auth
# Add a second OpenRouter key
hermes auth pool add openrouter --key "sk-or-v1-backup-key"
hermes auth pool strategy openrouter round_robin
# List all credentials
hermes auth pool list
# Remove a pool entry
hermes auth pool remove openrouter --index 1
The credential pool is persisted in the encrypted auth store (`~/.hermes/auth.json`), not in plaintext `.env` files. When a request to a provider fails with a 401, 429, or 402 status, Hermes automatically marks that credential as exhausted and rotates to the next one in the pool.
3.4 Toolsets: What They Are and How to Configure
A **toolset** is a named group of tools that you can enable or disable as a unit. Hermes ships with ~40+ tools organized into ~30 named toolsets.
Core Toolsets
| Toolset | Description | Default? |
|---|---|---|
| `web` | Web search (`web_search`, `web_extract`) | ✅ Always |
| `terminal` | Shell command execution (`terminal`, `process`) | ✅ Always |
| `file` | File read/write/patch/search | ✅ Always |
| `browser` | Full web browser automation | ⬜ Off by default |
| `vision` | Image analysis | ✅ Always |
| `image_gen` | Image generation | ⬜ Off by default |
| `code_execution` | Run Python scripts that call tools via RPC | ✅ Always |
| `skills` | Create, view, and manage skills | ✅ Always |
| `memory` | Persistent cross-session memory | ✅ Always |
| `session_search` | Search past conversations | ✅ Always |
| `delegation` | Spawn subagents for parallel work | ✅ Always |
| `cronjob` | Schedule recurring tasks | ⬜ Off by default (CLI only) |
| `clarify` | Ask you clarifying questions | ✅ Always |
| `todo` | Task planning and tracking | ✅ Always |
| `tts` | Text-to-speech output | ⬜ Off by default |
| `moa` | Mixture of Agents (advanced reasoning) | ⬜ Off by default |
| `homeassistant` | Smart home control | ⬜ Requires HASS_TOKEN |
| `kanban` | Multi-agent coordination board | ⬜ Off by default |
| `search` | Web search only (no scraping) | ⬜ Off by default |
| `messaging` | Cross-platform message sending | ✅ Always (gated on gateway) |
| `computer_use` | macOS desktop control | ⬜ Requires cua-driver |
| `video` | Video analysis | ⬜ Off by default |
| `video_gen` | Video generation | ⬜ Off by default |
Enabling and Disabling Toolsets
# Interactive tool management (recommended)
hermes tools
# Or via CLI commands
hermes tools enable browser
hermes tools disable code_execution
# List all toolsets and their status
hermes tools list
The `hermes tools` command opens an interactive TUI where you can toggle each toolset on or off, see which tools belong to each set, and preview which models support all your active tools.
How Toolsets Affect Conversation
Each toolset adds its tools to the LLM's function-calling schema. More tools = larger prompt = more tokens consumed. Best practice:
- **Start conservative** — use the defaults
- **Enable toolsets reactively** — when you need browser automation, enable `browser`
- **Disable what you don't need** — `hermes tools disable moa` saves ~300 tokens/turn
- **Create composite toolsets** — toolsets can include other toolsets (e.g., `debugging` includes `web`, `file`, and `terminal`)
Platform-Specific Toolsets
Each platform has its own toolset that inherits from the core tools:
- `hermes-cli` — full interactive CLI
- `hermes-telegram` — Telegram bot (terminal has safety checks)
- `hermes-discord` — Discord bot (+ Discord-specific tools)
- `hermes-slack` — Slack bot
- `hermes-whatsapp` — WhatsApp bot
- `hermes-cron` — Cron scheduler agent
You configure each independently. Browser automation might be fine in the CLI but disabled on Telegram.
Custom Toolsets
You can define custom toolset compositions in `config.yaml`:
toolsets:
custom:
my-workflow:
description: "Tools I need for daily dev work"
tools:
- web_search
- terminal
- read_file
- write_file
includes:
- vision
3.5 Profiles
Profiles let you run **multiple independent Hermes instances** on the same machine, each with its own config, API keys, memory, skills, sessions, and gateway.
When to Use Profiles
- **Work/Personal separation** — different models, different API keys, different skills
- **Multi-tenant servers** — each user gets their own profile
- **Kanban workers** — specialized profiles for different task categories
- **Testing** — a "default" profile for daily use, an "experimental" profile for new models
Profile Architecture
Profiles live under `~/.hermes/profiles/
~/.hermes/profiles/coder/
├── config.yaml # Independent config
├── .env # Independent API keys
├── sessions/ # Separate conversation history
├── skills/ # Different skills
├── memories/ # Separate memory
├── logs/ # Separate logs
├── cron/ # Separate scheduled jobs
└── home/ # Isolated subprocess HOME (git config, ssh, etc.)
Profile Commands
# Create a new profile
hermes profile create coder
# Creates ~/.hermes/profiles/coder/ with bundled skills seeded
# Create with cloned config from the default profile
hermes profile create work --clone --clone-all
# List all profiles
hermes profile list
# Switch to a profile
hermes profile use coder
# This writes "coder" to ~/.hermes/active_profile
# All future `hermes` commands use the coder profile
# Use a profile for a single command
hermes -p coder chat -q "What's my schedule?"
# Profiles also get shell aliases:
# After `hermes profile create coder`, you can run:
coder chat
# Delete a profile (irreversible — removes all data!)
hermes profile delete coder
Profile Isolation
- **Gateway** — each profile can run its own gateway on different ports
- **Sessions** — completely separate — `hermes sessions list` only shows the active profile's sessions
- **Memory** — curated memory is per-profile
- **Subprocesses** — the `home/` directory isolates git, ssh, and npm configs per profile
3.6 Memory Backends
Hermes has three memory backends with different tradeoffs.
Built-in Memory (Default)
- **Storage:** `~/.hermes/memories/MEMORY.md` + `USER.md`
- **Mechanism:** The agent periodically writes curated knowledge to Markdown files. On session start, these files are loaded as system context.
- **Pros:** Zero setup, works offline, fully transparent (readable Markdown)
- **Cons:** Simple key-value, no semantic search or deduplication
**Config:**
memory:
provider: "default"
auto_save: true # Auto-persist after conversations
auto_save_threshold: 5 # Turns before prompting for memory
Honcho (Dialectic Memory)
- **Storage:** Honcho server (local or cloud)
- **Mechanism:** Maintains a dialectic user model — the agent updates its understanding of you with each conversation
- **Pros:** Sophisticated user modeling, web dashboard, good for chatbot use cases
- **Cons:** Requires Honcho server running
**Setup:** `hermes honcho start` or configure Honcho cloud. Config in `config.yaml`:
memory:
provider: "honcho"
honcho:
base_url: "http://localhost:8000"
token: "your-honcho-token"
Mem0
- **Storage:** Mem0 Platform API
- **Mechanism:** Automatic semantic deduplication and relevance scoring
- **Pros:** Smart deduplication, good recall for large knowledge bases
- **Cons:** Paid API, internet connection required
**Setup:**
# In ~/.hermes/.env:
MEM0_API_KEY=m0-your-key
Or via `~/.hermes/mem0.json`:
{
"api_key": "m0-your-key",
"api_type": "platform",
"user_id": "my-user"
}
3.7 TTS & STT Setup for Voice Mode
Voice mode lets you speak to Hermes and hear spoken responses.
Text-to-Speech (TTS) — Hermes Talks
| Provider | Quality | Cost | Config Key |
|---|---|---|---|
| **Edge TTS** | Good (free) | Free | `edge` (default) |
| **OpenAI TTS** | Excellent | Paid (per char) | `openai` |
| **ElevenLabs** | Excellent | Paid (per char) | `elevenlabs` |
| **xAI TTS** | Good | Paid | `xai` |
| **Gemini TTS** | Good | Free tier | `gemini` |
| **Piper TTS** | Decent | Free (local) | `piper` |
| **KittenTTS** | Good | Free (local) | `kittentts` |
# In config.yaml:
tts:
provider: edge # Default: free, no API key needed
voice: en-US-JennyNeural # Voice name (provider-specific)
For OpenAI TTS, set `OPENAI_API_KEY` or `VOICE_TOOLS_OPENAI_KEY` in `.env`.
Speech-to-Text (STT) — Hermes Listens
| Provider | Quality | Cost | Setup |
|---|---|---|---|
| **Faster-Whisper** | Good | Free (local) | `pip install faster-whisper` |
| **Groq Whisper** | Excellent | Free tier | Set `GROQ_API_KEY` |
| **OpenAI Whisper** | Excellent | Paid | Set `OPENAI_API_KEY` |
# In config.yaml:
stt:
provider: faster-whisper # Or: groq, openai
model: base.en # Model size (faster-whisper only)
language: en # Language hint
**Activating voice mode:**
# Inside a chat session
/voice on
# Or start with voice
hermes --voice
3.8 Security & Approval Modes
Hermes has a layered security system to prevent accidental dangerous operations.
Approval Modes
Controls whether the agent must ask for permission before running dangerous commands.
# In config.yaml:
security:
approval_mode: smart # Default: "smart" — let the LLM decide
| Mode | Behavior | When to Use |
|---|---|---|
| `manual` | Always prompt for dangerous commands | Maximum safety, shared systems |
| `smart` | Auxiliary LLM auto-approves low-risk commands; prompts for risky ones | Best balance (default) |
| `off` | Never prompt for approval | Trusted environments, automation |
What Counts as "Dangerous"
The approval system checks `terminal` tool commands against a pattern database. Examples that trigger approval:
- `rm -rf`, `dd`, `mkfs`, `fdisk` — destructive filesystem operations
- `curl ... | bash` — remote code execution
- `sudo`, `su`, `chmod 777` — privilege escalation
- `kill -9`, `pkill` — process termination
- `pip install`, `npm install` — package installation (can be configured per-package)
YOLO Mode
Sometimes you want zero friction. YOLO mode bypasses **all** approval prompts:
# Inside a session
/yolo # Toggle ON
/yolo # Toggle OFF
# Via env var
HERMES_YOLO_MODE=1 hermes chat
When YOLO is active, the status bar shows a red ⚠ YOLO indicator.
Allowlisting Commands
You can permanently allow specific commands in `config.yaml`:
security:
approval_allowlist:
- "apt update"
- "pip install requests"
- "git status"
# Or via pattern
approval_allowlist_patterns:
- "curl https://.*"
Secret Redaction
API keys and sensitive values in `.env` are automatically redacted from logs and conversation history. The `_secret_redact` utility strips patterns matching known API key formats from all agent outputs.
Subagent Auto-Approval
For automated workflows (cron jobs, batch runs), subagents can be configured to auto-approve dangerous commands:
delegation:
auto_approve: true # Subagents bypass approval prompts
3.9 Full Config Reference
Top-Level Keys
| Key | Type | Default | Description |
|---|---|---|---|
| `model` | dict/string | `""` | Model configuration (see below) |
| `provider` | string | `"auto"` | Legacy root-level provider fallback |
| `base_url` | string | `""` | Legacy root-level base URL fallback |
| `agent` | dict | See below | Agent behavior |
| `display` | dict | See below | CLI/UI display preferences |
| `terminal` | dict | See below | Terminal backend configuration |
| `browser` | dict | See below | Browser automation |
| `compression` | dict | See below | Context compression |
| `delegation` | dict | See below | Subagent settings |
| `code_execution` | dict | See below | Sandboxed code execution |
| `auxiliary` | dict | See below | Auxiliary model routing |
| `clarify` | dict | See below | Clarifying questions |
| `security` | dict | See below | Approval & security |
| `memory` | dict | See below | Memory backend |
| `tts` | dict | See below | Text-to-speech |
| `stt` | dict | See below | Speech-to-text |
| `voice` | dict | See below | Voice mode settings |
| `toolsets` | dict | `{}` | Custom toolsets |
| `credential_pool_strategies` | dict | `{}` | Per-provider pool strategy |
| `network` | dict | See below | Network preferences |
| `onboarding` | dict | `{}` | First-run hints |
`model` Section
model:
default: "openrouter/anthropic/claude-sonnet-4-20250514"
provider: "openrouter" # Provider plugin name
base_url: "" # Custom endpoint override
`agent` Section
agent:
max_turns: 90 # Max tool-calling iterations
verbose: false # Show all tool I/O
system_prompt: "" # Custom system prompt override
prefill_messages_file: "" # File with initial messages
reasoning_effort: "" # none/minimal/low/medium/high/xhigh
service_tier: "" # OpenAI Priority tier
personalities: # Built-in personalities
helpful: "You are a helpful, friendly AI assistant."
concise: "You are a concise assistant..."
# ... (10+ built-in personalities)
`display` Section
display:
compact: false # Minimal output mode
resume_display: full # Show full or compact on session resume
show_reasoning: false # Display <thinking> blocks
streaming: true # Stream tokens in real-time
busy_input_mode: interrupt # interrupt/queue/steer
persistent_output: true # Persist output after new input
persistent_output_max_lines: 200
skin: default # Theming skin
`terminal` Section
terminal:
env_type: local # local/docker/ssh/modal/daytona/singularity
cwd: "." # Working directory
timeout: 60 # Per-command timeout (seconds)
lifetime_seconds: 300 # Session max lifetime
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
docker_volumes: [] # host:container mounts
docker_mount_cwd_to_workspace: false
`security` Section
security:
approval_mode: smart # manual/smart/off
approval_allowlist: []
approval_allowlist_patterns: []
`compression` Section
compression:
enabled: true # Auto-compress near context limit
threshold: 0.50 # Compress at 50% of context capacity
`network` Section
network:
force_ipv4: false # Prefer IPv4 (fixes IPv6 timeout issues)
3.10 Recommended Config for Beginners
Here's a complete, safe starting config that works immediately after installation:
# ~/.hermes/config.yaml — Recommended Beginner Config
model:
# Start with OpenRouter — one key for 200+ models
default: "openrouter/anthropic/claude-sonnet-4-20250514"
provider: "openrouter"
agent:
max_turns: 90
verbose: false
reasoning_effort: "" # Let the model decide
terminal:
env_type: local
cwd: "." # Your current directory
timeout: 120 # 2 minutes per command
security:
approval_mode: smart # Safe default — LLM decides when to ask
# Add safe commands to the allowlist:
approval_allowlist:
- "ls"
- "cat"
- "pwd"
- "pip install"
- "npm install"
- "git status"
- "git diff"
display:
streaming: true
show_reasoning: false
skin: default
compression:
enabled: true
threshold: 0.50
memory:
provider: "default" # Built-in — no setup needed
tts:
provider: edge # Free, no API key needed
# Don't forget to add your API keys to ~/.hermes/.env:
# OPENROUTER_API_KEY=sk-or-v1-...
**Setup checklist:**
1. ✅ Copy this config to `~/.hermes/config.yaml`
2. ✅ Add API key to `~/.hermes/.env`
3. ✅ Run `hermes model` to verify your provider
4. ✅ Run `hermes tools` and disable any toolsets you don't need
5. ✅ Run `hermes` and start chatting!
Key Takeaways
- **Two config files:** `config.yaml` for settings, `.env` for secrets
- **25+ providers** supported through a unified plugin architecture
- **Credential pools** provide automatic failover between multiple API keys for the same provider
- **Toolsets** group tools logically — enable only what you need to save tokens
- **Profiles** run completely isolated Hermes instances from one machine
- **Memory backends** range from simple Markdown files to semantic Mem0
- **Security modes** let you balance friction vs. safety — from `manual` to `yolo`
- **Config hierarchy** means environment variables always win for emergency overrides
**Next:** Module 4 — Daily Usage & Power Features. Learn the slash commands, session management, cron jobs, delegation, checkpoints, and more.