> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/based-ai/hermes-agent.md).

# Hermes Agent

Connect Nous Research's Hermes Agent CLI to the Based AI Inference Gateway as a custom OpenAI-compatible endpoint.

[Hermes Agent](https://hermes-agent.nousresearch.com/) is a CLI AI assistant from Nous Research that helps with coding, research, file management, and web browsing. Because Based AI exposes an [OpenAI-compatible Chat Completions API](/docs/based-ai/ai-inference-gateway.md), you can point Hermes at the Based AI Gateway and run any of its supported models — billed pay-per-use against your gateway balance.

This guide walks through adding Based AI as a **custom (direct API)** provider in Hermes.

## Prerequisites

* **Hermes Agent installed** — follow the [Hermes install guide](https://hermes-agent.nousresearch.com/docs/).
* **A Based AI API key** — create one at [ai.based.one/api-tokens](https://ai.based.one/api-tokens). You'll paste it during setup.
* **A funded balance** — hold >$1 in USDC/USDH or top up a credit balance so requests can settle. See [AI Inference Gateway](/docs/based-ai/ai-inference-gateway.md#billing).

{% hint style="info" %}
Based AI uses the OpenAI Chat Completions format. The base URL is `https://ai.based.one/v1` and requests go to the `/chat/completions` endpoint.
{% endhint %}

## Setup

{% stepper %}
{% step %}
**Start the model setup**

Run the guided setup from your terminal:

```bash
hermes setup model
```

When asked to **Select provider**, choose **`custom (direct API)`**.

![Select custom (direct API) as the Hermes provider](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-3b5d5c66b12d10733fe8f89f15e1b84b3777ed08%2F1.png?alt=media)
{% endstep %}

{% step %}
**Enter the Based AI base URL**

At the `API base URL` prompt, enter the Based AI Gateway endpoint:

```
https://ai.based.one/v1
```

![Enter https://ai.based.one/v1 as the API base URL](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-81a265115e390851dfe7f95b7f4ba98f611653fa%2F2.png?alt=media)
{% endstep %}

{% step %}
**Paste your API key**

At the `API key [optional]` prompt, paste the token you created at [ai.based.one/api-tokens](https://ai.based.one/api-tokens).

![Paste your Based AI API key](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-bca13bffb9cbe537c62cf944bf47b1b2491381c7%2F3.png?alt=media)

Hermes verifies the endpoint and confirms the models available on your account.
{% endstep %}

{% step %}
**Choose Chat Completions compatibility**

When prompted to **Select API compatibility mode**, choose **`2. Chat Completions`**. This routes requests to `/chat/completions`, the standard OpenAI-compatible path that Based AI uses.

![Select Chat Completions as the API compatibility mode](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-4d756be89c37b4d98c3cb540408e0a3e3c405530%2F4.png?alt=media)
{% endstep %}

{% step %}
**Pick a model**

Select a model by number, or type its name directly (for example `moonshotai/kimi-k2.5`).

![Select a model from the Based AI gateway](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-2c6dddb235fccde0030499508bc59cd809d0b71d%2F5.png?alt=media)
{% endstep %}

{% step %}
**Set context length and display name**

Leave **Context length** blank to let Hermes auto-detect it.

![Leave context length blank for auto-detect](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-c4963ca67d2501ba8e4591b7650096bb413ea1fa%2F6.png?alt=media)

Give the provider a **Display name** so it's easy to recognize later — for example `BasedAI`.

![Set a display name such as BasedAI](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-14935b83a4c02e41219f6ac221e04036f7cfb3e4%2F7.png?alt=media)
{% endstep %}

{% step %}
**Done**

Hermes saves the configuration to your custom providers and sets the model as default.

![Configuration complete — saved to custom providers as BasedAI](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-2a8ed4e0845fa5e31762e0ee7369a017976cea6b%2F8.png?alt=media)
{% endstep %}
{% endstepper %}

## Start chatting

Hermes is now running on Based AI. Send a message and your selected model responds — every request settles against your gateway balance.

![Hermes running on a Based AI model](https://893698931-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD195DGgjp8wD1XdWWTcZ%2Fuploads%2Fgit-blob-1c8b20f0b0108252e155aa075b874323adff5c6f%2F9.png?alt=media)

## Manage the connection

* **Switch models or update settings** — re-run `hermes setup model`, or edit the saved provider in your Hermes `config.yaml`.
* **Track spending** — view request history, token counts, and cost on the [Usage page](/docs/based-ai/ai-inference-gateway.md#usage) at [ai.based.one](https://ai.based.one/).
* **Rotate keys** — manage or revoke tokens anytime at [ai.based.one/api-tokens](https://ai.based.one/api-tokens).

{% hint style="info" %}
Supported models and pricing change over time. Check [ai.based.one](https://ai.based.one/) for the current model list and rates.
{% endhint %}