---
title: Hermes Agent
---


[Hermes Agent](https://hermes-agent.nousresearch.com) is an open-source terminal coding and task agent from Nous Research. It supports custom OpenAI-compatible providers, so a little config gets you onto the CrossModel catalog.

## Quickstart

### 1. Install Hermes Agent

```bash
pip install hermes-agent
hermes postinstall
```

Reload your shell afterward (`source ~/.zshrc` or `source ~/.bashrc`).

### 2. Create an API key

Sign in to the [Console](/console/api-keys) and create a key that starts with `cm-` on the **API Keys** page. The key is shown only once, so copy it somewhere safe.

### 3. Add your API key

Hermes Agent keeps secrets in `~/.hermes/.env`. In custom-provider mode it reads the key from `OPENAI_API_KEY` by default — put your CrossModel `cm-` key there:

```bash
OPENAI_API_KEY=cm-YOUR_KEY
```

<Callout type="info">
  The variable is named `OPENAI_API_KEY`, but the value should be your CrossModel `cm-` key.
</Callout>

### 4. Point Hermes at CrossModel

CrossModel isn't a built-in Hermes provider, so wire it up as a custom OpenAI-compatible one. Edit `~/.hermes/config.yaml`:

```yaml
model:
  provider: custom
  default: deepseek/deepseek-v4-pro
  base_url: https://api.crossmodel.ai/v1
```

### 5. Launch

```bash
hermes
```

Or use the modern terminal UI:

```bash
hermes --tui
```

## How it works

With `model.provider` set to `custom` and a `base_url` provided, Hermes Agent skips its built-in providers and sends requests straight to the OpenAI-compatible endpoint you specify (`https://api.crossmodel.ai/v1`), authenticated with the key from `~/.hermes/.env`.

Hermes keeps secrets (`.env`) separate from other settings (`config.yaml`): the key lives in `.env`, while model and interface settings live in `config.yaml`.

## Choosing models

To switch models, just change `model.default` in `config.yaml`, using the `vendor/short_name` format — e.g. `deepseek/deepseek-v4-flash` or `anthropic/claude-sonnet-4.6`. See the full list in the [model catalog](/models).

## Troubleshooting

| Symptom | What to check |
|---------|---------------|
| "Missing API key" | Confirm `OPENAI_API_KEY` is set in `~/.hermes/.env` to a valid `cm-` key. |
| Auth failure (401/403) | Check that the key is valid and your account has balance. |
| "Model not found" | Verify `model.default` matches an ID from the `/v1/models` response. |
| Insufficient balance | Top up in the [Console](/console/billing). |