Hermes Agent Integration with The Grid | Provider Setup

Connect Hermes Agent to The Grid as a custom provider. Update config.yaml, set your API key, patch redirects, and route agent runs.

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. There is no published uvx hermes-agent package; install from source. Windows runs under WSL2 only.

• A Grid account at 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.

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.

Setup

1. Save your Grid key

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:

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

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.

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.

3. Patch Hermes' HTTP client to follow redirects (required)

This is required, not optional troubleshooting. The Grid redirects consumption requests from /v1/chat/completions to /r/v1/chat/completions 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:

return _httpx.Client(
    transport=_httpx.HTTPTransport(socket_options=_sock_opts),
    proxy=_proxy,
    follow_redirects=True,
)

Verify the patch landed exactly once:

grep -c "follow_redirects=True" ~/.hermes/hermes-agent/run_agent.py

1 means the patch is in place. 0 means it didn't apply.

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.

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.

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:

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

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 <consumption API key>. 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 <KEY>"
   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=<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

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.

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.

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

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.

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.

HTTP 402 Payment Required. Your credits are at zero. Top up at app.thegrid.ai. For graceful degradation, point fallback_model at a different provider (OpenRouter or local Ollama).

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.

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.