> 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

[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](/files/cQVnC7Zac4mS4QDTLDpm)
{% 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](/files/0NnLXL6u9H5dpRLCdaE2)
{% 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](/files/D4Uj2suZLeKISSDWqvUS)

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](/files/U9O9m65wHKrw1MzFR4YH)
{% 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](/files/lfOCTf8nPnO9VM3tKoZd)
{% 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](/files/F0OTbMojdOBrGspvLaU7)

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

![Set a display name such as BasedAI](/files/TDbPvvsU19USmjN1R2qX)
{% 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](/files/e5GtkYv5vxLREYMBjN1n)
{% 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](/files/uRQ5DRe4Eq62u6KS4hij)

## 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 %}