# Hermes Agent Hermes Agent talks to The Grid the same way it talks to Ollama, vLLM, or any other OpenAI-compatible endpoint: as a custom provider. No plugin, one config block, and the messaging gateway, cron scheduler, and sub-agents all route through it. There are two gotchas in current Hermes builds that catch nearly every new user. Both are documented below as required setup steps -- not as troubleshooting -- so read the whole Setup section before you start editing files. ## Prerequisites * Hermes Agent installed from the [Hermes GitHub repo](https://github.com/NousResearch/hermes-agent). There is no published `uvx hermes-agent` package; install from source. Windows runs under WSL2 only. * A Grid account at [app.thegrid.ai](https://app.thegrid.ai). * Credits in your account. The Grid is prepaid; zero credits returns 402. * A Grid consumption API key from **Settings → API Keys → Create Consumption Key**. {% hint style="info" %} **Shell vs in-chat REPL.** Commands like `hermes chat`, `hermes config set`, `hermes model`, `hermes doctor` run in your terminal. Slash commands like `/model`, `/usage`, `/exit` run inside an active Hermes chat session. Don't type `hermes model` inside the REPL — it sends as a chat message and won't do anything. {% endhint %} ## Setup ### 1. Save your Grid key ```bash hermes config set THEGRID_API_KEY your-consumption-api-key ``` `hermes config set` auto-routes API keys to `~/.hermes/.env`. Editing the file directly works too. ### 2. Make The Grid your active provider in `~/.hermes/config.yaml` This is the step new users miss most often. Hermes routes inference based on the top `model:` block of `config.yaml`. If you only add an entry to `custom_providers:`, your existing provider (Gemini, OpenRouter, Anthropic, whatever) stays as the default and your messages get routed there with a model name like `custom:thegrid:agent-prime` -- which that other provider has never heard of, producing a confusing 404 from a host that isn't even The Grid. To make The Grid the default, the top `model:` block must look like this: ```yaml model: default: agent-prime provider: custom base_url: https://api.thegrid.ai/v1 api_key: ${THEGRID_API_KEY} context_length: 256000 ``` Pick the path that fits your situation: #### Path A: interactive wizard ```bash hermes model ``` Choose **Custom endpoint (self-hosted / VLLM / etc.)** from the provider list. Then: * API base URL: `https://api.thegrid.ai/v1` * API key: paste, or press Enter to use the value already saved in `.env` * Model name: `agent-prime` * Context length: `256000` Hermes writes this to `~/.hermes/config.yaml`. #### Path B: edit `config.yaml` directly Paste the `model:` block above. The `api_key: ${THEGRID_API_KEY}` line is required even with the key in `.env`. In recent Hermes versions, setting `THEGRID_API_KEY` in `~/.hermes/.env` is not enough on its own when using a custom `base_url`; the `model:` block has to reference the variable explicitly. {% hint style="warning" %} **Adding to `custom_providers:` alone does not change your default.** If your top `model:` block points at OpenRouter, Gemini, Anthropic, or anything else, your messages still go there. The named-provider entry under `custom_providers:` only enables mid-session switching with `/model custom:thegrid:agent-prime`. To make The Grid the default, update the top `model:` block as shown. {% endhint %} ### 3. Patch Hermes' HTTP client to follow redirects (required) This is required, not optional troubleshooting. The Grid redirects `POST /v1/chat/completions` to `synapse.thegrid.ai` for routing, and Hermes' bundled `httpx.Client` does not follow redirects by default. Without the patch, every chat message returns HTTP 307 with an HTML error page. Open `~/.hermes/hermes-agent/run_agent.py`, find the `_build_keepalive_http_client()` static method, and add `follow_redirects=True` to the `httpx.Client(...)` constructor: ```python return _httpx.Client( transport=_httpx.HTTPTransport(socket_options=_sock_opts), proxy=_proxy, follow_redirects=True, ) ``` Verify the patch landed exactly once: ```bash grep -c "follow_redirects=True" ~/.hermes/hermes-agent/run_agent.py ``` `1` means the patch is in place. `0` means it didn't apply. {% hint style="warning" %} **The patch is temporary.** Any `hermes update` or `git pull` inside `~/.hermes/hermes-agent/` overwrites `run_agent.py` and you'll need to reapply. The proper fix needs to land upstream in Hermes itself. Track or open an issue on the Hermes GitHub repo if you want to follow the upstream resolution. {% endhint %} ### 4. Restart Hermes Fully exit any running Hermes session (`Ctrl+D` in the REPL or close the terminal) so the patched file is loaded fresh. Restarting in-place is not enough -- the Python process keeps the old module in memory. ```bash hermes chat ``` ### 5. (Optional) Add The Grid alongside other providers If you already have OpenRouter, Anthropic, or Nous Portal configured and want to keep them, register The Grid as a named custom provider so it sits next to them: ```yaml custom_providers: - name: thegrid base_url: https://api.thegrid.ai/v1 key_env: THEGRID_API_KEY api_mode: chat_completions ``` Switch mid-session with `/model custom:thegrid:agent-prime` (or any other instrument). Adding this entry does not change your default — the top `model:` block from Step 2 still controls that. ### 6. (Optional) Tier auxiliary tasks Hermes splits the main loop from auxiliary tasks (vision, web summarization, session search). Point auxiliary tasks at Text Standard so cheap work stays cheap. The same pattern works for cron jobs that run unattended. ## Verification ```bash hermes chat ``` Inside the session, switch to The Grid if it isn't your default: ``` /model custom:thegrid:agent-prime ``` Try something representative: "Search my home directory for files changed in the last 24 hours, summarize what changed, and write the summary to `~/changes.md`." If Hermes executes tool calls, returns a coherent text summary (not an HTML error block), and writes the file, the integration works end to end. ## Copy-paste prompt — let your existing AI assistant set this up for you If you already have a working AI coding assistant (Cursor, Claude Code, OpenAI Codex CLI, Aider, anything with shell access), paste this prompt to it. The assistant will walk through every step on your machine, including the redirect patch, and verify each one before moving on. ``` I want to use The Grid (an OpenAI-compatible AI inference market at https://api.thegrid.ai/v1) as my primary LLM provider in Hermes Agent. Set this up for me end-to-end. Context you need: - The Grid's API is OpenAI-compatible. Base URL: https://api.thegrid.ai/v1. - Auth: Authorization: Bearer . NOT a trading key — trading keys 401. - Default Hermes instrument: agent-prime (256K context, multi-step tool use). - Hermes config lives at ~/.hermes/config.yaml. Secrets at ~/.hermes/.env. Source repo at ~/.hermes/hermes-agent/. Walk through these steps. After each step, run the verification command and only proceed if it passes: 1. Ask me for my Grid consumption API key. I'll get it from app.thegrid.ai → Settings → API Keys → Create Consumption Key. Paste-validate it with: curl -sS -L -o /dev/null -w "%{http_code}\n" https://api.thegrid.ai/v1/models -H "Authorization: Bearer " 200 = valid consumption key. 401 = wrong key (likely a trading key); ask me to regenerate. 2. Save the key to ~/.hermes/.env as `THEGRID_API_KEY=` (do NOT hardcode in config.yaml). Verify with: grep "^THEGRID_API_KEY=" ~/.hermes/.env 3. Read ~/.hermes/config.yaml and find the current top `model:` block. Tell me what provider is currently set. Then update the top `model:` block (replace it, do not just append a custom_providers entry) to: model: default: agent-prime provider: custom base_url: https://api.thegrid.ai/v1 api_key: ${THEGRID_API_KEY} context_length: 256000 Adding to custom_providers alone does NOT change the default — the top model: block must point at The Grid for chat messages to route there. Verify with: grep -A 5 "^model:" ~/.hermes/config.yaml 4. Patch ~/.hermes/hermes-agent/run_agent.py: find the `_build_keepalive_http_client()` static method (search for that exact name), and add `follow_redirects=True` to the httpx.Client(...) constructor inside it. Result should look like: return _httpx.Client( transport=_httpx.HTTPTransport(socket_options=_sock_opts), proxy=_proxy, follow_redirects=True, ) This is required because The Grid redirects POST /v1/chat/completions to synapse.thegrid.ai and Hermes' default httpx.Client doesn't follow redirects — without this patch every chat message returns HTTP 307 with an HTML error page. Verify exactly once: grep -c "follow_redirects=True" ~/.hermes/hermes-agent/run_agent.py Expected: 1. Then validate the file still parses: ~/.hermes/hermes-agent/venv/bin/python -c "import ast; ast.parse(open('/Users/$(whoami)/.hermes/hermes-agent/run_agent.py').read()); print('SYNTAX OK')" Tell me explicitly: this patch is temporary. Any `hermes update` or git pull will overwrite run_agent.py and the patch must be reapplied. 5. Tell me to fully exit any running Hermes session (Ctrl+D in the REPL or close the terminal — restarting in-place doesn't reload the patched module) and run `hermes chat` in a fresh terminal. Inside that session I should send a real message and confirm it returns a coherent text response, NOT an HTML error block. Don't ask me to choose a model — agent-prime is the right default for Hermes. Don't add anything to custom_providers unless I tell you I want multiple providers configured side by side. ``` ## Troubleshooting {% hint style="warning" %} **404 from Gemini, OpenRouter, or another provider mentioning `models/custom:thegrid:...`.** You added The Grid to `custom_providers:` but the top `model:` block still points at the old provider. Update the top `model:` block as shown in Setup Step 2. Adding the named-provider entry alone does not change the default. {% endhint %} {% hint style="warning" %} **HTTP 307 or HTML error page in the chat response.** Hermes' HTTP client isn't following The Grid's redirect from `/v1/chat/completions` to `synapse.thegrid.ai`. Apply the patch in Setup Step 3 if you skipped it, or reapply it if a `hermes update` wiped the file. Check with `grep -c "follow_redirects=True" ~/.hermes/hermes-agent/run_agent.py` — `0` means the patch is missing. {% endhint %} {% hint style="warning" %} **"No inference provider configured" error on first launch.** Hermes' empty-state error message lists OpenRouter and OpenAI as examples. It does not mention `THEGRID_API_KEY`, but that's what you need. Set `THEGRID_API_KEY` in `~/.hermes/.env` and configure the custom provider per Step 2. {% endhint %} {% hint style="warning" %} **HTTP 503 — "Balance replenishment in progress. Please retry shortly."** Your Grid Consumption Account balance is at zero or being topped up. Wait 30–60 seconds and try again. If it persists, check your balance at app.thegrid.ai. If you have Auto Top Up enabled, confirm your payment method is valid. {% endhint %} {% hint style="warning" %} **HTTP 401 Unauthorized.** You used a Grid trading key, not a consumption key. Trading keys do not authorize inference. Also confirm `api_key: ${THEGRID_API_KEY}` in `config.yaml` matches the variable name in `.env`. {% endhint %} {% hint style="warning" %} **HTTP 402 Payment Required.** Your credits are at zero. Top up at [app.thegrid.ai](https://app.thegrid.ai). For graceful degradation, point `fallback_model` at a different provider (OpenRouter or local Ollama). {% endhint %} {% hint style="info" %} **Sharing `hermes config show` output.** Hermes expands `${THEGRID_API_KEY}` in the displayed `model:` block, so the raw consumption key ends up in the output. Redact the `api_key:` line before pasting into Discord, GitHub issues, or Slack. {% endhint %} {% hint style="info" %} **Connection diagnostic.** `hermes doctor` runs a diagnostic sweep. Confirm `provider` is set to `custom` (unquoted), `base_url` is exactly `https://api.thegrid.ai/v1`, and that `THEGRID_API_KEY` resolves in your shell. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/hermes-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.