> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Hermes Agent (gateway)

> Set up Hermes Agent with the Respan gateway.

Route [Hermes Agent](https://hermes-agent.nousresearch.com)'s LLM calls through the Respan gateway for automatic logging, caching, and model switching. Hermes talks to any OpenAI-compatible endpoint, so only your `RESPAN_API_KEY` is needed.

## Setup

#### Install Hermes Agent

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

On Windows PowerShell:

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

#### Point Hermes at the Respan gateway

Edit `~/.hermes/config.yaml` and set a custom OpenAI-compatible provider:

```yaml
model:
  default: gpt-4o
  provider: custom
  base_url: "https://api.respan.ai/api"
  api_key: "YOUR_RESPAN_API_KEY"
```

Or run the interactive picker, choose **Custom endpoint (self-hosted / VLLM / etc.)**, and enter the same base URL, key, and model name:

```bash
hermes model
```

No separate provider key needed. The Respan gateway handles provider authentication.

#### Run Hermes

```bash
hermes
```

For a one-shot, non-interactive run:

```bash
hermes chat -q "your prompt" --oneshot
```

All LLM calls now route through Respan.

> **Note**
>
> Set the gateway in `config.yaml` (or with `hermes model`), not through `OPENAI_BASE_URL` and `OPENAI_API_KEY`. Hermes only reads those variables for its `openai-api` provider, which sends OpenAI-only parameters such as `reasoning.effort` and fails on non-reasoning models.

## Switch models

Change `model.default` in `~/.hermes/config.yaml` to use any of the 1000+ models available through the gateway.

```yaml
model:
  default: gpt-4o
  # default: claude-sonnet-4-5-20250929
  # default: gemini/gemini-3.5-flash
```

See the [full model list](https://platform.respan.ai/platform/models).