---
title: "Hermes Agent integration"
description: "Settings for using Hermes Agent with MiniRouter."
canonical_url: "https://minirouter.sh/docs/integrations/hermes"
markdown_url: "https://minirouter.sh/docs/integrations/hermes.md"
last_updated: "2026-09-26"
---

# Hermes Agent

Run Hermes Agent on any MiniRouter model through its custom endpoint.

[Get a key](https://minirouter.sh/key)

[Hermes Agent](https://hermes-agent.nousresearch.com/docs) is Nous Research's always-on personal agent. Add MiniRouter as its custom endpoint to run it on any model in the [catalog](https://minirouter.sh/models), move side tasks to cheaper models, and cap unattended spend with [rate limits](https://minirouter.sh/docs/rate-limits).

> **Note:** Hermes sends MiniRouter IDs unchanged, as in `zai/glm-5.3-flash`. No prefix needed.

## Quick start

### 1. Install Hermes

**macOS / Linux**

```sh
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

**Windows**

```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```

### 2. Save your key

[Create a key](https://minirouter.sh/key), then add it to Hermes's env file.

```sh
MINIROUTER_KEY=mr-live-YOUR-KEY-HERE
```

> **Tip:** Give the agent its own key with a daily cap. A retry loop then stops at the cap, not at your balance.

### 3. Point Hermes at MiniRouter

**Wizard**

```sh
hermes model
```

| Setting | Value |
| --- | --- |
| `hermes model` | Custom endpoint (self-hosted / VLLM / etc.) |
| `model.base_url` | `https://api.minirouter.sh/v1`. Paste it complete, including /v1. |
| `model.provider` | `custom` |
| `model.default` | `zai/glm-5.3-flash` |
| `model.key_env` | `MINIROUTER_KEY` |
| `MINIROUTER_KEY` | `mr-live-… (your key)`. In ~/.hermes/.env, not config.yaml. |

**config.yaml**

```yaml
model:
  provider: custom
  base_url: https://api.minirouter.sh/v1
  default: zai/glm-5.3-flash
  key_env: MINIROUTER_KEY
```

### 4. Start and verify

```sh
hermes
```

Send one message, then open [Activity](https://minirouter.sh/dashboard/activity). The request lists its model, tokens and exact cost. If nothing arrives, run `hermes doctor`.

## Switch models

| Where | Scope |
| --- | --- |
| `/model custom:openai/gpt-5.6-luna` | This session. |
| `/model custom:openai/gpt-5.6-sol --once` | The next turn only. |
| `/model custom:openai/gpt-5.6-luna --global` | This session and new ones. |
| `hermes chat -m openai/gpt-5.6-luna` | One run. |
| `model.default` | New sessions, in `~/.hermes/config.yaml`. |

| Model ID | Answers with |
| --- | --- |
| `minirouter/auto` | A model [Auto](https://minirouter.sh/docs/auto-router) picks. Tool calls get a tool-capable one. |
| `@preset/your-slug` | Your saved [preset](https://minirouter.sh/docs/presets), editable in the [dashboard](https://minirouter.sh/dashboard/presets). |

> **Warning:** `/model` reads `:` as a provider separator. Put IDs with `:`, such as `minirouter/auto:code`, in `model.default`.

## Run from scripts

`-m` overrides the model for that run only.

```sh
hermes -z "Summarize today's inbox" \
  -m zai/glm-5.3-flash \
  --usage-file usage.json
```

| Command | Prints |
| --- | --- |
| `hermes -z` | The final answer only. |
| `hermes chat --oneshot -q` | The answer and tool output, then exits. |

## Move side tasks and add fallbacks

Compression, vision and titles run on your main model unless you move them. A fallback takes over when the main model fails.

```yaml
auxiliary:
  compression:
    base_url: https://api.minirouter.sh/v1
    model: deepseek/deepseek-v4-flash-0731
    api_key: ${MINIROUTER_KEY}

fallback_providers:
  - provider: custom
    model: openai/gpt-5.6-luna
    base_url: https://api.minirouter.sh/v1
    key_env: MINIROUTER_KEY
```

Compare rates for side-task models on [Models](https://minirouter.sh/models), or read [Model fallbacks](https://minirouter.sh/docs/model-fallbacks) for server-side fallbacks.

## Keep spend in check

- [Own key](https://minirouter.sh/dashboard/keys): One key for this agent.
- [Spend cap](https://minirouter.sh/docs/rate-limits): Daily or monthly limit on that key.
- [Activity](https://minirouter.sh/dashboard/activity): Every request and its cost.

Restrict models or filter content with [Guardrails](https://minirouter.sh/docs/guardrails).

## Recommended models

| Model | Why |
| --- | --- |
| [`zai/glm-5.3-flash`](https://minirouter.sh/models/zai/glm-5.3-flash) | Strong agentic performance at a low input rate for repeated tool schemas. |
| [`openai/gpt-5.6-luna`](https://minirouter.sh/models/openai/gpt-5.6-luna) | Low-cost, high-intelligence alternative for routine agent turns. |
| [`deepseek/deepseek-v4-flash-0731`](https://minirouter.sh/models/deepseek/deepseek-v4-flash-0731) | Lowest input rate among the high-scoring long-context candidates. |
| [`tencent/hy3`](https://minirouter.sh/models/tencent/hy3) | Lower-capability fallback with inexpensive input for high-volume loops. |

Browse every model in the [catalog](https://minirouter.sh/models).

## Troubleshooting

### Provider loads but every model call 404s

Paste https://api.minirouter.sh/v1 complete, including the /v1. These clients treat the base URL as the OpenAI-compatible root and append /chat/completions themselves, so trimming the /v1 leaves them calling a path that does not exist.

Error: [400 `invalid_request`](https://minirouter.sh/docs/errors#invalid_request).

### Credits gone overnight with nothing to show

An agent in a retry loop spends at machine speed. Set dailyLimitNano on the key the agent uses — one key per agent, so a runaway is contained to that key rather than the whole balance.

Error: [402 `insufficient_credits`](https://minirouter.sh/docs/errors#insufficient_credits).

### 401 on every request

Wrong or rotated key. Keys start with mr-live-; after a rotation the old key keeps working for 24 hours, then dies.

Error: [401 `invalid_api_key`](https://minirouter.sh/docs/errors#invalid_api_key).

### Response stops mid-sentence with a credits message

Balance hit $0 mid-stream. The stream ends with a terminal error naming the exact charge for tokens delivered — never a silent close.

Error: [402 `insufficient_credits`](https://minirouter.sh/docs/errors#insufficient_credits).

Every error code, with its fix: [Errors](https://minirouter.sh/docs/errors).

## Next steps

- [Guardrails](https://minirouter.sh/docs/guardrails): Budgets and model lists per key.
- [Rate limits](https://minirouter.sh/docs/rate-limits): Cap spend and requests per key.
- [Personal agents](https://minirouter.sh/use/personal-agents): Models and spend for always-on agents.