Hermes Agent

Connect Hermes Agent to CoffeeRouter through its interactive custom endpoint configuration.

Before you begin

  • Create an active token in the CoffeeRouter console and make sure it can access the chat model you intend to use.
  • Note the exact model ID. Hermes requires the selected model to support a context window of at least 64K tokens.
  • Use https://www.coffeerouter.ai/v1 as the CoffeeRouter API base URL.

Configuration steps

1. Install Hermes Agent

On macOS, Linux, WSL2, or Termux, run the official installer:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

On Windows, install it natively from PowerShell:

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

Reopen your terminal or reload your shell configuration as instructed by the installer, then verify the installation:

hermes --version

2. Add the CoffeeRouter custom endpoint

Start the model configuration wizard:

hermes model

Choose Custom endpoint (self-hosted / VLLM / etc.), then enter:

FieldValue
API Base URLhttps://www.coffeerouter.ai/v1
API Keysk-your-api-key
ModelThe exact model ID shown by CoffeeRouter

3. Review or edit the configuration

The wizard saves the Hermes configuration. To review it, open ~/.hermes/config.yaml; the relevant section should look like this:

model:
    default: your-model-id
    provider: custom
    base_url: https://www.coffeerouter.ai/v1
    api_key: sk-your-api-key

The model ID must exactly match a model available to your CoffeeRouter token. Prefer the hermes model wizard so that unrelated settings in the file remain intact.

Verify the connection

Start Hermes and send a test message:

hermes

You can also launch the terminal UI:

hermes --tui

If Hermes returns a response and /model shows the model you configured, the connection is working.

Troubleshooting

Why does the configured model fail to start?

Confirm that the model ID exactly matches CoffeeRouter and that the model supports at least a 64K context window. Hermes rejects models with a smaller context window.

Why do requests return 401?

Copy the complete token again and verify that it is enabled, unexpired, and has available quota. Do not add spaces or quotation marks around the API key.

Is WSL2 required on Windows?

No. Hermes now provides a native PowerShell installer. WSL2 remains an option if you prefer a Linux environment.

Why does the base URL include /v1?

Hermes expects the base address of an OpenAI-compatible API. CoffeeRouter exposes that API at https://www.coffeerouter.ai/v1.

Security

A CoffeeRouter token is an account credential. Do not share configuration files, terminal screenshots, or logs that contain it. Create a dedicated Hermes token so you can separately restrict models, quota, and IP addresses, and revoke it when a device is lost or retired.

Official resources