--- name: hermes-agent-setup description: Help users configure Hermes Agent — CLI usage, setup wizard, model/provider selection, tools, skills, voice/STT/TTS, gateway, and troubleshooting. Use when someone asks to enable features, configure settings, or needs help with Hermes itself. version: 1.1.1 author: Hermes Agent tags: [setup, configuration, tools, stt, tts, voice, hermes, cli, skills] --- # 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: ```bash hermes profile list hermes profile create --clone-all --no-alias hermes --profile status --all hermes --profile 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://: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: ```bash 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: ```bash 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): ```bash cd ~/.hermes/hermes-agent source venv/bin/activate pip install faster-whisper ``` Add to config.yaml under the `stt:` section: ```yaml 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): | Provider | Env var | Free? | |----------|---------|-------| | ElevenLabs | ELEVENLABS_API_KEY | Free tier | | OpenAI | VOICE_TOOLS_OPENAI_KEY | Paid | | Kokoro (local) | None needed | Free | | Fish Audio | FISH_AUDIO_API_KEY | Free tier | ### 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: ```bash 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: ```bash hermes --profile tools disable --platform cli terminal file code_execution browser delegation cronjob hermes --profile tools disable --platform telegram terminal file code_execution browser delegation cronjob hermes --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: | Toolset | What it provides | |---------|-----------------| | terminal | Shell command execution | | file | File read/write/search/patch | | web | Web search and extraction | | browser | Browser automation (needs Browserbase) | | image_gen | AI image generation | | mcp | MCP server connections | | voice | Text-to-speech output | | cronjob | Scheduled tasks | ## Installing Dependencies Some tools need extra packages: ```bash 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: ```yaml # 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: ```bash 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: ```bash 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: ```bash 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 '' 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) | Command | What it does | |---------|-------------| | /reset or /new | Fresh session (picks up new tool config) | | /help | Show all commands | | /model [name] | Show or change model | | /compact | Compress conversation to save context | | /voice [mode] | Configure voice replies | | /reasoning [effort] | Set reasoning level | | /sethome | Set home channel for cron/notifications | | /restart | Restart the gateway (picks up config changes) | | /status | Show session info | | /retry | Retry last message | | /undo | Remove last exchange | | /personality [name] | Set agent personality | | /skill [name] | Load a skill | ## 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: ```bash # 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: ```bash hermes auth list # Every credential in every pool, with auth type + status hermes auth status # 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/getMe"` 2. Check webhook status: `curl -s "https://api.telegram.org/bot/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`