hermes-agent-setup

Hermes Agent Setup & Configuration

Use this skill when a user asks about configuring Hermes, enabling features, setting up voice, managing tools/skills, or troubleshooting.

Key Paths

• Config: ~/.hermes/config.yaml
• API keys: ~/.hermes/.env
• Skills: ~/.hermes/skills/
• Hermes install: ~/.hermes/hermes-agent/
• Venv: ~/.hermes/hermes-agent/venv/

CLI Overview

Hermes is used via the hermes command (or python -m hermes_cli.main from the repo).

Core commands:

hermes                          Interactive chat (default)
hermes chat -q "question"       Single query, then exit
hermes chat -m MODEL            Chat with a specific model
hermes -c                       Resume most recent session
hermes -c "project name"        Resume session by name
hermes --resume SESSION_ID      Resume by exact ID
hermes -w                       Isolated git worktree mode
hermes -s skill1,skill2         Preload skills for the session
hermes --yolo                   Skip dangerous command approval

Configuration & setup:

hermes setup                    Interactive setup wizard (provider, API keys, model)
hermes model                    Interactive model/provider selection
hermes config                   View current configuration
hermes config edit              Open config.yaml in $EDITOR
hermes config set KEY VALUE     Set a config value directly
hermes login                    Authenticate with a provider
hermes logout                   Clear stored auth
hermes doctor                   Check configuration and dependencies

Tools & skills:

hermes tools                    Interactive tool enable/disable per platform
hermes skills list              List installed skills
hermes skills search QUERY      Search the skills hub
hermes skills install NAME      Install a skill from the hub
hermes skills config            Enable/disable skills per platform

Gateway (messaging platforms):

hermes gateway run              Start the messaging gateway
hermes gateway install          Install gateway as background service
hermes gateway status           Check gateway status

Session management:

hermes sessions list            List past sessions
hermes sessions browse          Interactive session picker
hermes sessions rename ID TITLE Rename a session
hermes sessions export ID       Export session as markdown
hermes sessions prune           Clean up old sessions

Other:

hermes status                   Show status of all components
hermes cron list                List cron jobs
hermes insights                 Usage analytics
hermes update                   Update to latest version
hermes pairing                  Manage DM authorization codes

Setup Wizard (hermes setup)

The interactive setup wizard walks through: 1. Provider selection — OpenRouter, Anthropic, OpenAI, Google, DeepSeek, and many more 2. API key entry — stores securely in the env file 3. Model selection — picks from available models for the chosen provider 4. Basic settings — reasoning effort, tool preferences

Run it from terminal:

cd ~/.hermes/hermes-agent
source venv/bin/activate
python -m hermes_cli.main setup

To change just the model/provider later: hermes model

Skills Configuration (hermes skills)

Skills are reusable instruction sets that extend what Hermes can do.

Managing skills:

hermes skills list              # Show installed skills
hermes skills search "docker"   # Search the hub
hermes skills install NAME      # Install from hub
hermes skills config            # Enable/disable per platform

Per-platform skill control:

hermes skills config opens an interactive UI where you can enable or disable specific skills for each platform (cli, telegram, discord, etc.). Disabled skills won't appear in the agent's available skills list for that platform.

Loading skills in a session:

• CLI: hermes -s skill-name or hermes -s skill1,skill2
• Chat: /skill skill-name
• Gateway: type /skill skill-name in any chat

Voice Messages (STT)

Voice messages from Telegram/Discord/WhatsApp/Slack/Signal are auto-transcribed when an STT provider is available.

Provider priority (auto-detected):

1. Local faster-whisper — free, no API key, runs on CPU/GPU
2. Groq Whisper — free tier, needs GROQ_API_KEY
3. OpenAI Whisper — paid, needs VOICE_TOOLS_OPENAI_KEY

Setup local STT (recommended):

cd ~/.hermes/hermes-agent
source venv/bin/activate
pip install faster-whisper

Add to config.yaml under the stt: section:

stt:
  enabled: true
  provider: local
  local:
    model: base  # Options: tiny, base, small, medium, large-v3

Model downloads automatically on first use (~150 MB for base).

Setup Groq STT (free cloud):

1. Get free key from https://console.groq.com
2. Add GROQ_API_KEY to the env file
3. Set provider to groq in config.yaml stt section

Verify STT:

After config changes, restart the gateway (send /restart in chat, or restart hermes gateway run). Then send a voice message.

Voice Replies (TTS)

Hermes can reply with voice when users send voice messages.

TTS providers (set API key in env file):

Voice commands (in any chat):

• /voice on — voice reply to voice messages only
• /voice tts — voice reply to all messages
• /voice off — text only (default)

Enabling/Disabling Tools (hermes tools)

Interactive tool config:

cd ~/.hermes/hermes-agent
source venv/bin/activate
python -m hermes_cli.main tools

This opens a curses UI to enable/disable toolsets per platform (cli, telegram, discord, slack, etc.).

After changing tools:

Use /reset in the chat to start a fresh session with the new toolset. Tool changes do NOT take effect mid-conversation (this preserves prompt caching and avoids cost spikes).

Common toolsets:

Installing Dependencies

Some tools need extra packages:

cd ~/.hermes/hermes-agent && source venv/bin/activate

pip install faster-whisper    # Local STT (voice transcription)
pip install browserbase       # Browser automation
pip install mcp               # MCP server connections

Config File Reference

The main config file is ~/.hermes/config.yaml. Key sections:

# Model and provider
model:
  default: anthropic/claude-opus-4.6
  provider: openrouter

# Agent behavior
agent:
  max_turns: 90
  reasoning_effort: high    # xhigh, high, medium, low, minimal, none

# Voice
stt:
  enabled: true
  provider: local           # local, groq, openai
tts:
  provider: elevenlabs      # elevenlabs, openai, kokoro, fish

# Display
display:
  skin: default             # default, ares, mono, slate
  tool_progress: full       # full, compact, off
  background_process_notifications: all  # all, result, error, off

Edit with hermes config edit or hermes config set KEY VALUE.

Gateway Commands (Messaging Platforms)

Editing API Keys in .env

The ~/.hermes/.env file is a protected credential file — the patch and write_file tools will refuse to edit it. To update API keys, use sed via the terminal:

# Update a specific key (use | as delimiter to avoid escaping issues with keys containing /)
sed -i 's|^KEY_NAME=.*|KEY_NAME=new-value-here|' ~/.hermes/.env

# Verify the change
grep '^KEY_NAME=' ~/.hermes/.env

Common keys to update: - VOICE_TOOLS_OPENAI_KEY — OpenAI TTS and Whisper STT - FAL_KEY — fal.ai image generation - GROQ_API_KEY — Groq Whisper STT - ELEVENLABS_API_KEY — ElevenLabs TTS - FIRECRAWL_API_KEY — Firecrawl web tools - BROWSERBASE_API_KEY — Browser automation

After updating keys, restart the gateway or start a new CLI session for changes to take effect.

Troubleshooting

Voice messages not working

1. Check stt.enabled is true in config.yaml
2. Check a provider is available (faster-whisper installed, or API key set)
3. Restart gateway after config changes (/restart)

Tool not available

1. Run hermes tools to check if the toolset is enabled for your platform
2. Some tools need env vars — check the env file
3. Use /reset after enabling tools

Model/provider issues

1. Run hermes doctor to check configuration
2. Run hermes login to re-authenticate
3. Check the env file has the right API key

Checking which auth method a provider uses (OAuth subscription vs API key)

Do NOT just grep ~/.hermes/config.yaml. Provider credentials live in the credential pool, not (only) in config.yaml. hermes config show will report a provider as (not set) even when an OAuth credential is active in the pool, because that view only reflects env-var/API-key auth.

Authoritative inspection commands:

hermes auth list                  # Every credential in every pool, with auth type + status
hermes auth status <provider>     # Just one provider, e.g. anthropic / nous / openai-codex / openrouter / custom:venice-ai

hermes auth list output decodes as:

anthropic (1 credentials):
  #1  anthropic-oauth-3   oauth   hermes_pkce   exhausted (55m 8s left)
       │                  │       │             └─ status: ready | exhausted (NNm left) | error
       │                  │       └─ source: hermes_pkce (OAuth) | env:VAR_NAME | model_config | device_code
       │                  └─ auth type: oauth | api_key
       └─ credential id/label

Mapping auth type → billing: - oauth + source hermes_pkce or device_code → subscription (Claude.ai Pro/Max, ChatGPT, Nous portal) - api_key + source env:FOO or model_config → pay-as-you-go API credits

exhausted (NNm left) on a subscription means the rolling-window quota (e.g. Claude's 5-hour window) is spent and will auto-reset; Hermes falls back to other pool members in the meantime. The credential_pool_strategies: block in config.yaml (e.g. anthropic: round_robin) only controls how the pool is rotated — it does not by itself imply a provider is configured.

When the user asks "am I on subscription or API credits?", the answer comes from hermes auth list, not from config.yaml.

Telegram bot not responding

1. Check the bot token is valid: curl -s "https://api.telegram.org/bot<TOKEN>/getMe"
2. Check webhook status: curl -s "https://api.telegram.org/bot<TOKEN>/getWebhookInfo" - Hermes uses long polling by default (webhook url should be empty) - If TELEGRAM_WEBHOOK_URL is set in .env, it uses webhook mode instead
3. Verify the gateway is ACTUALLY running — hermes gateway status can report a stale PID. Cross-check with ps aux | grep gateway
4. If the gateway process died, restart it: hermes gateway start (if installed as service) or hermes gateway run
5. Check for API errors: tail -30 ~/.hermes/logs/errors.log — HTTP 529 means the model provider is overloaded

Changes not taking effect

• Gateway: /reset for tool changes, /restart for config changes
• CLI: start a new session

Skills not showing up

1. Check hermes skills list shows the skill
2. Check hermes skills config has it enabled for your platform
3. Load explicitly with /skill name or hermes -s name