> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Add NagaAI to Hermes Agent by Nous Research as a named provider on the Responses API, with the key read from NAGA_API_KEY.

[Hermes Agent](https://hermes-agent.nousresearch.com/docs/) by Nous Research connects to NagaAI as a named custom provider in `~/.hermes/config.yaml`. Hermes then sends its requests to the NagaAI Responses API and uses any NagaAI chat model by its catalog id. The setup follows the [Hermes custom provider docs](https://hermes-agent.nousresearch.com/docs/integrations/providers#named-custom-providers) for Hermes Agent v0.22.5.

## Before you start

You need a NagaAI [API key](https://naga.ac/dashboard/api-keys) and Hermes Agent installed. On Linux, macOS or WSL2, the official installer sets it up:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

For Windows and the desktop app, see [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation).

## Connect Hermes Agent

**1. Save the key**

Hermes reads secrets from the environment and from `~/.hermes/.env`. Add the key there, so every Hermes session finds it:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
echo 'NAGA_API_KEY=ng-your-key' >> ~/.hermes/.env
```

**2. Add the provider**

Add a `nagaai` entry under `providers` in `~/.hermes/config.yaml`, and make it the default model:

```yaml theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
providers:
  nagaai:
    name: NagaAI
    api: https://api.naga.ac/v1
    key_env: NAGA_API_KEY
    transport: codex_responses
    models:
      claude-sonnet-5:
        context_length: 1000000
      deepseek-v4.1-flash:
        context_length: 1048576

model:
  default: claude-sonnet-5
  provider: custom:nagaai
```

`transport: codex_responses` is Hermes's name for the Responses API, so Hermes calls `POST /v1/responses`. `key_env` names the variable that holds the key, so the key itself stays out of the config file.

**3. Set the context windows**

Give each model you use a `context_length`, taken from `limits.context_window` of the model's `chat` operation in [`/v1/models`](https://docs.naga.ac/get-started/models). Hermes decides when to compress the conversation from this number. Without it, Hermes guesses the window from public model data.

**4. Check the connection**

Send one question and exit:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
hermes chat --oneshot -q "Reply with the word ready."
```

The answer comes from `claude-sonnet-5` on NagaAI. Inside a session, `/model custom:nagaai:deepseek-v4.1-flash` switches to another model from the list.

## Troubleshooting

### 401 invalid\_api\_key

Hermes found no key or a wrong one. Check that `~/.hermes/.env` holds `NAGA_API_KEY` with an API key, not a provisioning key, and start a new session.

### 400 model\_not\_found

The model id in `model.default` or in `/model` isn't in the catalog. Copy the id from [naga.ac/models](https://naga.ac/models).

### Hermes compresses the conversation too early

The model has no `context_length` under `providers.nagaai.models`, and Hermes guessed a smaller window than the model has. Add the model's window from `/v1/models`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.