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

Profiles / tenant-style Hermeses

Use profiles when the user wants separate Hermes personas, Telegram bots, memories, skills, sessions, model settings, or gateway state:

hermes profile list
hermes profile create <name> --clone-all --no-alias
hermes --profile <name> status --all
hermes --profile <name> chat -q 'Reply with exactly: ok' -Q

For a customer-facing or sandboxed tenant, profiles are necessary but not sufficient: profiles isolate Hermes state, while tool policies and containers/VMs provide capability and OS boundaries. See references/profile-tenant-sandboxing.md for the safe default flow, toolsets to disable, containerized Spawn-style architecture, and Telegram BotFather token-provisioning caveats.

Desktop remote backend / VPS dashboard

When the user wants the new Hermes Desktop app to connect to a Hermes instance running on a VPS, use the dashboard backend as the remote target. The Desktop setting is Settings → Gateway → Remote gateway → Remote URL, and the URL should normally be http://<tailscale-or-vps-ip>:9119 or an HTTPS proxy to that dashboard.

Use references/desktop-remote-dashboard.md for the PM2 setup, verification commands, and security caveats. Important pitfall: the Desktop remote URL is the dashboard port (9119 by default), not the messaging gateway API port (8642). Prefer Tailscale or nginx/HTTPS/basic-auth for durable exposure; hermes dashboard --host 0.0.0.0 --insecure is only acceptable as a short-lived test.

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.).

Command-line tool policy

For tenant/profile setup, prefer explicit per-platform CLI commands and verify afterwards:

hermes --profile <profile> tools disable --platform cli terminal file code_execution browser delegation cronjob
hermes --profile <profile> tools disable --platform telegram terminal file code_execution browser delegation cronjob
hermes --profile <profile> tools list --platform telegram

Default disabled toolsets for sandboxed/customer-facing tenants: - terminal — shell commands, installs, process/service control, deployments - file — local read/write/search/patch - code_execution — Python/script execution - browser — interactive browser actions and form submissions - delegation — subagents / parallel autonomous workers - cronjob — persistent scheduled autonomy

Keep memory and session_search only when cross-session continuity is part of the product; they are privacy-sensitive even though they are not shell-level dangerous.

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

# Side-task LLM routing: compression, vision, title generation, session search, etc.
auxiliary:
  compression:
    provider: auto
    model: ""
  vision:
    provider: auto
    model: ""

# Delegated subagents
delegation:
  provider: ""
  model: ""

# Image generation plugin routing
image_gen:
  provider: fal
  model: ""

# 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.

OpenAI Codex-centric routing

When the user wants Hermes to run primarily through a ChatGPT/OpenAI Codex subscription, update the main model and the side-task routes. Do not stop at model.provider / model.default; auxiliary calls and subagents can still use other providers.

Use references/openai-codex-routing.md for the detailed workflow. The compact pattern is:

hermes config set model.provider openai-codex
hermes config set model.default gpt-5.5
hermes config set model.reasoning_effort low
hermes config set delegation.provider openai-codex
hermes config set delegation.model gpt-5.5
hermes config set auxiliary.compression.provider openai-codex
hermes config set auxiliary.compression.model gpt-5.5
hermes config set auxiliary.vision.provider openai-codex
hermes config set auxiliary.vision.model gpt-5.5
hermes config set image_gen.provider openai-codex
hermes config set image_gen.model gpt-image-2-medium

If a smaller/faster OpenAI Codex model is available in the local install, prefer it for auxiliary.* and delegation.* while leaving the main model on the strongest default.

GPT-5.6 Sol/Terra/Luna: Pro mode vs Codex Max

OpenAI's GPT-5.6 API uses three actual model IDs: gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna (gpt-5.6 aliases Sol). Pro is a Responses API execution mode, not a -pro model suffix: direct API requests use reasoning: {mode: "pro", effort: "..."}. Do not configure gpt-5.6-sol-pro, gpt-5.6-terra-pro, or gpt-5.6-luna-pro unless a provider's live model catalog explicitly returns those IDs.

The ChatGPT-account openai-codex backend is a separate surface. Verify it from the live endpoint rather than assuming public API parity:

hermes chat -q 'Reply with exactly: OK' -Q --provider openai-codex -m gpt-5.6-sol

As verified live on 2026-07-09, Codex OAuth exposed only the three standard GPT-5.6 slugs. It accepted reasoning.effort: max and returned effective reasoning.mode: standard, but rejected reasoning.mode: pro with HTTP 400 (reasoning.mode is not supported with this model). Its live catalog described: - Sol: low, medium, high, xhigh, max, ultra - Terra: low, medium, high, xhigh, max, ultra - Luna: low, medium, high, xhigh, max

For the strongest single-agent Hermes configuration on a ChatGPT/Codex subscription, use:

hermes config set model.provider openai-codex
hermes config set model.default gpt-5.6-sol
hermes config set agent.reasoning_effort max

agent.service_tier: fast / /fast is Priority Processing (latency), not Pro reasoning mode. Codex ultra means automatic task delegation/subagents and is also distinct from API Pro mode. Hermes may not expose ultra through its reasoning parser even when the backend advertises it.

Known picker pitfall: Hermes builds around 2026-07-09 could synthesize GPT-5.6 -pro slugs in hermes_cli/codex_models.py even though the live Codex endpoint did not return them. The resulting picker entries fail with The '<slug>' model is not supported when using Codex with a ChatGPT account. Treat the live endpoint and a smoke request as authoritative.

See references/gpt-5.6-codex-pro-mode.md for the public-API-vs-Codex distinction, safe live-catalog inspection, streamed probe recipe, and verified Max/Pro behavior.

Smart model routing caveat

Before recommending smart_model_routing, verify the current checkout actually implements it. In the May 2026 checkout, config keys existed (enabled, max_simple_chars, max_simple_words, cheap_model) but no active Python implementation was found for the routing logic. Prefer explicit auxiliary, delegation, model.reasoning_effort, and toolset/skill trimming for speed/cost control unless the implementation is present.

Context compression / compaction troubleshooting

When Hermes reports that earlier messages were removed but summary generation was unavailable, inspect compression config, auxiliary routing, auth, and logs before explaining from memory. Use references/context-compression-troubleshooting.md for the detailed diagnostic workflow.

Key pitfall: if auxiliary.compression.provider is the same provider as model.provider (for example both openai-codex), the “main agent model” fallback is skipped after compression fails because it would retry the same backend. If there is no auxiliary.compression.fallback_chain, logs may say all fallbacks exhausted even though the provider is configured and small probes work. For high-value sessions, prefer compression.abort_on_summary_failure: true, a longer auxiliary.compression.timeout, and a real fallback provider for compression.

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

Vision / image analysis not working

If vision_analyze returns Error code: 404 - No endpoints found that support image input:

1. Check if primary model supports vision — models like deepseek/deepseek-v4-pro may have supports_vision: false.
2. Configure an explicit vision fallback — in current configs this usually lives under auxiliary.vision, not top-level vision. When auxiliary.vision.provider: auto and auxiliary.vision.model is empty, it may resolve to the primary model and fail.
3. Fix, using a known vision-capable provider/model for the user's current provider strategy: bash hermes config set auxiliary.vision.provider openai-codex hermes config set auxiliary.vision.model gpt-5.5 # or another verified vision-capable provider/model hermes gateway restart
4. For image generation, configure image_gen.provider / image_gen.model separately. Example for GPT Image 2 through Codex OAuth: bash hermes config set image_gen.provider openai-codex hermes config set image_gen.model gpt-image-2-medium
5. Pitfall: Do NOT fall back to mcp_claude_code_Read on image files — Claude Code's vision model can misinterpret raw JPEG data and hallucinate wrong content. If vision_analyze fails, tell the user honestly and fix the config.

See references/vision-fallback-config.md in the hermes-agent skill and references/openai-codex-routing.md in this skill for model options and verification.

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