Hermes

Hermes is an open-source agent from Nous Research. Its built-in hermes model wizard can add HiAPI as a custom endpoint, so you don’t need a third-party management tool. The steps below use claude-opus-5-5 as the example; this tutorial was verified on Windows with Hermes 0.22.5.

1. Install Hermes

1.1 Requirements

1.2 Windows (PowerShell)

Skip the setup wizard and only configure the model after installing:

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -SkipSetup

Standard install (opens the setup wizard):

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

1.3 macOS / Linux

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

1.4 Verify the install

Reopen the terminal and run:

hermes --version

Seeing the version number is enough; continue once there is output.

1.5 Other installation methods

The install script and version requirements follow the official Hermes installation docs.

2. Configure the HiAPI endpoint

Hermes has two model-related commands with different purposes; don’t mix them up:

To add HiAPI, use hermes model, so exit the session first (Ctrl+C or /quit).

2.1 Run the setup wizard

hermes model

Choose Custom endpoint (self-hosted / VLLM / etc.) (some versions show Custom endpoint (enter URL manually)).

2.2 Fill in each prompt

For Claude models, choose Anthropic Messages as the API compatibility mode. With claude-opus-5-5 as the example:

In Anthropic Messages mode, set the API base URL to the root address https://api.hiapi.ai without /v1; Hermes appends /v1/messages itself. The HiAPI API key is hidden or shown as asterisks while you type it; paste it and press Enter.

2.3 Connect GPT, DeepSeek and other models

For GPT, DeepSeek and other models, fill the other items as in the table above, change only the two below, and replace Model name with the matching model name. Note that the address here includes /v1.

The combinations tested for this tutorial are: Anthropic Messages for Claude, Chat Completions for GPT and DeepSeek. If a model does not support the chosen protocol, you get a 400.

2.4 Switch to another model

To switch models under the same endpoint, type this directly in a session:

/model custom:<model-id>

Or run hermes model again to change the default model. When switching to another model, find the model name in the text model list and confirm its context is at least 64K. More options for custom endpoints are in the Hermes custom endpoint docs.

3. Manual configuration (optional)

The manual configuration below works for GPT, DeepSeek and other models that use Chat Completions; for Claude, use the hermes model wizard above. If you can’t use the wizard, edit ~/.hermes/config.yaml directly (base_url must include /v1):

model:
  default: <model-id>
  provider: custom
  base_url: https://api.hiapi.ai/v1
  api_key: YOUR_HIAPI_API_KEY

You can also use an environment variable instead of a plaintext key; key_env is how Hermes reads an environment variable, so leave it as is:

model:
  default: <model-id>
  provider: custom
  base_url: https://api.hiapi.ai/v1
  key_env: HIAPI_API_KEY

Then write this in ~/.hermes/.env:

HIAPI_API_KEY=YOUR_HIAPI_API_KEY

Replace YOUR_HIAPI_API_KEY with your HiAPI API key. After changing the configuration, start a new session with /new or restart Hermes before testing.

4. Verify

4.1 Chat

Open Hermes, confirm it uses the HiAPI provider, and send “Hello, introduce yourself in one sentence.” A normal reply means the connection works.

4.2 Tool calling

First create tool-call-test.txt in the folder where you start Hermes, write one line hello hiapi and save it. Then send “Only call a tool once. Read the entire contents of tool-call-test.txt and return them exactly as they are. Do not guess the contents from the file name.” Confirm that a tool call appears and returns hello hiapi.

5. Troubleshooting

Only issues specific to Hermes are listed here. For common errors such as 401, 404 and 429, see Common errors.

This page only covers text models; for tool capabilities see the MCP guide.