# Hermes Agent

> Add Deference to Hermes Agent as a named provider in config.yaml.

Hermes Agent, from Nous Research, talks to custom endpoints in three formats: Chat Completions, Anthropic Messages and Responses. This guide uses Chat Completions with the base URL `https://deference.si/v1`.

## Set up

1. Create a key in [API keys](https://deference.si/keys).
2. Add the key to `~/.hermes/.env`. Hermes reads secrets from this file, not from `config.yaml`.

```bash
DEFERENCE_API_KEY=sk-df-...
```

3. Add the provider and make it the default model in `~/.hermes/config.yaml`.

```yaml
providers:
  deference:
    api: https://deference.si/v1
    key_env: DEFERENCE_API_KEY
    transport: chat_completions
    models:
      "anthropic/claude-sonnet-5.5":
        context_length: 200000

model:
  default: anthropic/claude-sonnet-5.5
  provider: custom:deference
```

Run `hermes config path` and `hermes config env-path` to print where Hermes keeps these two files on your system.

To set it up by prompts instead, run `hermes model` and choose **Custom endpoint**. It asks for the base URL, the key and the model, and for the API format.

## Verify

1. Run `hermes doctor`. It exits cleanly when nothing needs fixing.
2. Run `hermes status`. It shows the model and provider, and that credentials are present, without printing the key.
3. Start `hermes` and send a short message.
4. Open [Activity](https://deference.si/activity). The request is the top row, with the model you chose.

## Pick a model

* Hermes needs a context window of at least 64K tokens and refuses smaller ones at startup. List only models that meet it, and set `context_length` for each, because Hermes does not read it from `GET /v1/models`.
* Switch models in a session with `/model custom:deference:anthropic/claude-sonnet-5.5`. Add `--global` to keep the choice.
* `transport` can also be `anthropic_messages` or `codex_responses`. For `anthropic_messages`, the base URL is `https://deference.si`, without `/v1`. Set `transport` explicitly: Hermes otherwise guesses it from the URL.

## Troubleshooting

| You see                               | Cause                                                                  | Fix                                                   |
| ------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
| `401 invalid_api_key`                 | The key is not in `~/.hermes/.env`, or the name differs from `key_env` | Match the names, then run `/reload` or restart Hermes |
| 401 with a placeholder key            | The setting is spelled `api_key_env`, and Hermes expects `key_env`     | Rename it to `key_env`                                |
| "context window below minimum 64,000" | `context_length` is missing or under 64K                               | Set it, and use a model with at least 64K             |
| `OPENAI_BASE_URL` has no effect       | Hermes honors it only for the `openai-api` provider                    | Use the `providers` block above                       |
| `404 model_not_found`                 | The id differs from the catalog                                        | Copy the id from the Models page                      |
| `402 insufficient_credit`             | No available credit                                                    | [Add credit](https://deference.si/wallet?tab=add)                         |