Hermes Agent

Get going in 30 seconds

Create ~/.hermes/config.yaml:

model:
  default: bedrock/global.anthropic.claude-sonnet-4-6-global
  provider: custom
  base_url: https://northerninference.ca/v1
  api_key: ni_live_YOUR_KEY_HERE

Then launch Hermes. It routes every request through Northern Inference.

Hermes Agent (Nous Research) is an OpenAI-compatible TUI coding agent. NI's gateway speaks the same /v1/chat/completions protocol, so it works as a drop-in backend.

1. Get an NI API key

northerninference.ca/portal → Keys → Create key. Copy the ni_live_... string (shown only once).

2. Configure Hermes

Create or edit ~/.hermes/config.yaml with your key and a deployed route:

model:
  default: bedrock/global.anthropic.claude-sonnet-4-6-global
  provider: custom
  base_url: https://northerninference.ca/v1
  api_key: ni_live_YOUR_KEY_HERE

Replace bedrock/global.anthropic.claude-sonnet-4-6-global with any route listed at northerninference.ca/portal → Models or returned by:

curl https://northerninference.ca/api/billing/models | jq '.models[].model_id'

Use the exact string, case-sensitive. Bare model names (e.g. claude-sonnet-4-6) are not route keys and will return a 400.

Alternative: no-edit setup via the wizard

Run the interactive model picker instead of editing the config file:

hermes model

Choose Custom endpoint (self-hosted / VLLM / etc.), then enter:

• URL: https://northerninference.ca/v1
• API key: your ni_live_... key
• Model: a deployed NI route (e.g. bedrock/global.anthropic.claude-sonnet-4-6-global)

The wizard writes the same config block shown above.

3. Choose a route

Two good starting points:

Copy the exact route string from the portal Models page or the catalog endpoint. Your API key's allowed route tiers control which routes the key may call.

4. Verify it is working

Start Hermes and send a message. Then check northerninference.ca/portal → Usage to confirm the request appeared within a few seconds.

You can also confirm routing with a direct call:

curl https://northerninference.ca/v1/chat/completions \
  -H "Authorization: Bearer $NI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/global.anthropic.claude-sonnet-4-6-global",
    "messages": [{"role": "user", "content": "say hi"}],
    "max_tokens": 10
  }'

The response will include X-NI-Custody-Path, X-NI-Resolved-Jurisdiction, and X-NI-Request-ID headers confirming NI handled the request.

Troubleshooting

"Invalid API key" error. Confirm the value in config.yaml starts with ni_live_ and has no trailing whitespace. Regenerate the key from the portal if needed.

**"model not found" or 400 from NI.** The default value in config.yaml must match an exact deployed route. Run curl https://northerninference.ca/api/billing/models | jq '.models[].model_id' and paste one of those strings verbatim.

Request does not appear in portal Usage. Hermes may be connecting to a different endpoint. Confirm base_url is exactly https://northerninference.ca/v1 (with /v1, no trailing slash) and provider is custom.

Want to scope spend per project? Issue a separate NI key per project from the portal, set the key's Max spend per day limit, and update api_key in the config.