Hermes | OpenModels Documentation

Use OpenModels as the upstream model provider for Hermes Agent. Hermes keeps its CLI, TUI, memory, skills, terminal backends, messaging gateway, cron jobs, and tools. OpenModels provides the OpenAI-compatible model endpoint, API key, model IDs, and credit-based billing.

This guide focuses on Hermes calling OpenModels. If you want another app to call Hermes through its API server, see “Use Hermes as an OpenAI-compatible endpoint” below.

When to use this

Use this setup when you want:

Hermes Agent as a local or always-on autonomous agent.
OpenModels as the model marketplace behind Hermes.
One ale-... OpenModels API key for Hermes model calls.
OpenAI-compatible chat completions through https://api.getopenmodels.com/v1.
Hermes features such as memory, skills, messaging platforms, web tools, and terminal execution on top of OpenModels-backed models.

Prerequisites

Hermes Agent installed on the machine that will run the CLI, TUI, or gateway.
An OpenModels API key in the ale-... format.
Available credits in your OpenModels account.
A supported OpenModels chat model with at least 64K context. Hermes rejects smaller context windows because multi-step tool workflows need enough working memory.

Good starting models:

Use case	Model
General chat and low-cost testing	`qwen3.5-flash`
Coding-heavy agent work	`kimi-k2.7-code`
Reasoning or larger project context	Pick a high-context reasoning model from the Models page

1. Install Hermes

On Linux, macOS, WSL2, or Android Termux:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc   # or: source ~/.zshrc

On Windows PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Verify the install:

hermes doctor

2. Store your OpenModels key

Hermes stores secrets in ~/.hermes/.env. Put the OpenModels key there:

mkdir -p ~/.hermes
printf 'OM_API_KEY=ale-your-api-key\n' >> ~/.hermes/.env

Do not commit real ale-... keys to an application repository.

3. Configure OpenModels as a named custom provider

Hermes supports custom OpenAI-compatible endpoints. Use a named custom provider so the model reference is explicit and easy to switch later.

Edit ~/.hermes/config.yaml:

custom_providers:
  - name: openmodels
    base_url: https://api.getopenmodels.com/v1
    key_env: OM_API_KEY
    api_mode: chat_completions
    models:
      "qwen3.5-flash":
        context_length: 1000000
      "kimi-k2.7-code":
        context_length: 256000
model:
  provider: custom:openmodels
  default: qwen3.5-flash

Notes:

base_url is the OpenModels base URL.
key_env points Hermes to OM_API_KEY in ~/.hermes/.env.
api_mode: chat_completions keeps Hermes on the OpenAI-compatible chat completions path.
context_length should match or conservatively fit the selected model. Use the OpenModels Models page as the current source.

If you already have custom_providers or model config, merge these keys into the existing YAML instead of adding duplicate top-level keys.

4. Start Hermes with OpenModels

Start the CLI or TUI:

hermes
hermes --tui

The startup banner should show the selected provider and model. Send a simple prompt that is easy to verify:

Summarize the current directory in five bullets.

If Hermes responds normally and can use tools, the OpenModels-backed setup is working.

5. Switch models during a session

Use Hermes’ /model command to switch to another OpenModels model:

/model custom:openmodels:kimi-k2.7-code

Switch back to the configured default:

/model default

Hermes writes model choices to ~/.hermes/config.yaml for new sessions. Existing chat sessions can keep the model they started with, so use /model when you want to switch inside the active session.

6. Add gateway or automation only after chat works

Once a normal CLI or TUI chat works, add the next Hermes layer:

hermes gateway setup
hermes tools
hermes skills browse

Use hermes gateway setup for Telegram, Discord, Slack, WhatsApp, Email, Home Assistant, Microsoft Teams, and other messaging platforms. Keep model setup simple until the base chat is stable.

Use Hermes as an OpenAI-compatible endpoint

This is the reverse direction: another app calls Hermes, and Hermes runs its configured agent.

Hermes has an API server feature for OpenAI-compatible frontends. In that mode:

The external app talks to Hermes’ API server URL.
Hermes uses its configured provider, which can be OpenModels.
The OpenModels key stays inside ~/.hermes/.env, not in the frontend app.

Keep these endpoints separate:

Direction	Base URL
Hermes calls OpenModels directly	`https://api.getopenmodels.com/v1`
Another app calls Hermes	Your local or deployed Hermes API server URL

Do not expose a Hermes API server publicly without authentication, network controls, and a clear tool-permission model. Hermes can run terminal commands, access files, and use configured tools.

Troubleshooting

Symptom	Check
Hermes reports missing API key	Confirm `OM_API_KEY` is present in `~/.hermes/.env`
OpenModels returns `401` or invalid key	Confirm the key is a valid `ale-...` key and still active in OpenModels
Balance or billing failure	Add credits to the OpenModels account before sending requests
Hermes rejects the model at startup	Use an OpenModels chat model with at least 64K context and set `context_length`
Custom endpoint works in another client but not Hermes	Check `base_url`, `api_mode`, model ID, and `key_env`
Current chat keeps using the old model	Use `/model custom:openmodels:<model-id>` inside the active session
Gateway starts but messages fail	First verify plain `hermes` or `hermes --tui`, then re-run `hermes gateway setup`