# Hermes Agent

Connect [Nous Research's Hermes Agent](https://hermes-agent.nousresearch.com/)
to Aurora as a custom OpenAI-compatible endpoint. Aurora supplies inference;
Hermes runs the agent tools and manages sessions.

> Available Inference endpoint: `https://ai.aur.lu/v1` (Aurora).

## Install and prepare

Follow the [Hermes installation guide](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
for your operating system. Create an [Aurora token](https://docs.aur.lu/docs/inference/getting-started).

Store this entry in `~/.hermes/.env` (create the file if needed):

```dotenv
AURORA_API_TOKEN=<your-token>
```

If you use a Hermes profile or custom `HERMES_HOME`, use that profile's `.env`
and `config.yaml`. Keep the secret file out of source control.

## Configure the main model

In `~/.hermes/config.yaml`, replace the existing `model` value with this mapping:

```yaml
model:
  provider: custom
  default: deepseek/deepseek-v4-flash
  base_url: https://ai.aur.lu/v1
  api_key: ${AURORA_API_TOKEN}
  api_mode: chat_completions
```

Use the complete Aurora model ID. Hermes expands environment references in
configuration from its environment and `.env`; `api_mode: chat_completions`
selects the supported API explicitly.

For interactive setup, run `hermes model` **outside a chat session**, choose
**Custom endpoint**, and enter the selected base URL, Aurora token, and model ID.
Check the resulting configuration uses Chat Completions. The `/model` command
inside a session switches existing providers; it does not perform initial setup.

## Start and verify

From the project directory:

```bash
hermes chat
```

Ask:

```text
Read README.md and summarize the project in three bullets. Do not edit files.
```

Use an existing text file accessible to the configured terminal backend. Expect
a file-tool result and a summary. With a Docker or remote backend, host files
must be available in that backend's workspace.

Start a new session after editing the main model configuration. Existing chats
can retain their model selection. Hermes manages streaming for the session.

## Auxiliary models and troubleshooting

Hermes has separate model slots for compression, titles, vision, and other tasks.
Review them in **Models → Show auxiliary**, particularly on an existing install.
Text tasks can use the main Aurora model; vision requires a vision-capable model,
and speech or image generation needs a separately configured service.

- **Wrong endpoint:** Set `model.base_url` in YAML. `OPENAI_BASE_URL` applies to
  Hermes' `openai-api` provider, not this custom-provider configuration.
- **Token unresolved:** Check the active profile's `.env` and restart the client.
- **New model not taking effect:** Open a new session or explicitly switch the
  active session with `/model`.
- **Tool or compression errors:** Check the tool backend and auxiliary model
  assignments as well as the main connection.

See [shared troubleshooting](https://docs.aur.lu/docs/inference/integrations#troubleshooting),
[Hermes custom endpoints](https://hermes-agent.nousresearch.com/docs/integrations/providers#custom--self-hosted-llm-providers),
and [model configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models).