Connect Hermes Agent to Zukko — Anthropic or OpenAI

Hermes Agent connects to Zukko with a regular API key — no Claude or ChatGPT subscription needed. The key is to pick the right option in the wizard and not mix up the base URL: no /v1 for Anthropic, with /v1 for OpenAI. Below are both options step by step, ready-made configs, and common errors.

What Hermes Agent is

Hermes Agent↗ is an autonomous AI agent from Nous Research. It runs in the terminal, has a desktop app and messaging integrations; it keeps context across sessions and creates skills as it works. The model is configured separately: Hermes supports many providers, including Anthropic and OpenAI via an API key.

With Zukko, one fetch_... key gives Hermes access to Claude, GPT, and GLM. The gateway accepts both request formats, so any model in the catalog can be called through either the Anthropic option or the OpenAI option.

If Hermes isn't installed yet, on Linux, macOS, and WSL2 it's one command:

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

For Windows and the desktop app, see the installation guide on the Hermes website.

Step 1. Run the setup wizard

If a Hermes chat is open, exit it (Ctrl+C or /quit) and run in the terminal:

hermes model

hermes model is the full provider setup wizard: it adds providers, takes keys, and saves the config. Pick one of two options from the list:

• Anthropic — Claude models via API key or Claude Code
• OpenAI — Codex CLI or direct OpenAI API

Both work through Zukko; the only difference is the request format.

Option 1: Anthropic

In the wizard:

The wizard saves the key to ~/.hermes/.env, so you don't need to write anything there by hand. Then set the Zukko address in ~/.hermes/config.yaml:

model:
  provider: anthropic
  default: claude-sonnet-5
  base_url: https://api.zukko.pro

base_url goes without /v1: the Anthropic SDK inside Hermes adds the path itself.

Start Hermes:

hermes

Inside the chat, switch models with /model.

Option 2: OpenAI

In the wizard:

The key and address live in ~/.hermes/.env:

OPENAI_API_KEY=fetch_...
OPENAI_BASE_URL=https://api.zukko.pro/v1

Or set the address in ~/.hermes/config.yaml:

model:
  provider: openai-api
  default: claude-sonnet-5
  base_url: https://api.zukko.pro/v1

Here base_url goes with /v1. According to the Hermes docs, OPENAI_BASE_URL is honored only for the openai-api provider.

With this option you can use any Zukko model: claude-sonnet-5, claude-opus-5-5, gpt-5.6-sol, gpt-5.6-luna, glm-5.3, glm-5.3-flash.

Which option to choose

If you mostly work with Claude, the Anthropic option is the natural fit. If you want to switch between Claude, GPT, and GLM within one provider, the OpenAI option is more convenient. More on the formats in Anthropic or OpenAI↗.

What it costs

Zukko prices per 1M tokens (input/output): claude-sonnet-5, claude-opus-5-5, and gpt-5.6-sol — $0.30/$0.30; gpt-5.6-luna and glm-5.3 — $0.10/$0.10; glm-5.3-flash — $0.04/$0.04. With every step the agent sends a large context to the model (instructions, memory, history), so most of the spend is input tokens. Zukko bills cached tokens at the regular input price, while vendors charge around 10% of the input price for cache reads, so for long agent sessions the real difference from the official price list is smaller than a direct price comparison suggests. Set a daily limit on the key so the agent can't spend more than planned.

Verify the connection

1. Get a key on the API keys page↗.
2. Go through the hermes model wizard using one of the options above.
3. Run hermes and ask any question.
4. Open Usage in the dashboard — the request should appear there.

If it fails

401 unauthorized

The key is mistyped, revoked, or copied with spaces. Check it on the keys page↗.

402

Your balance has run out. Top up↗ and retry.

404 with the Anthropic option

base_url must not include /v1. Correct: https://api.zukko.pro; wrong: https://api.zukko.pro/v1.

The OpenAI option goes to the wrong place or returns 404

Make sure that:

1. The provider is openai-api.
2. The base URL includes /v1: https://api.zukko.pro/v1.
3. OPENAI_API_KEY contains your fetch_... key.

The wizard offers Codex CLI or Claude Code OAuth

Those options are for official subscriptions and don't work with Zukko. Choose:

• for Anthropic — API key;
• for OpenAI — direct OpenAI API.

FAQ

Anthropic or OpenAI: which should I pick?

It's a choice of request format, not of model: the whole Zukko catalog is available through either. To see which model handles your tasks better, test it yourself — give Hermes the same task on claude-sonnet-5 and gpt-5.6-sol and compare the results and the spend in the dashboard.

How do I switch between providers?

Set up both options via hermes model. According to the Hermes docs, /model inside a chat only switches between providers and models you've already configured; new providers are added with hermes model in the terminal.

Does Hermes have a graphical interface?

According to the Hermes docs, besides the terminal there is a desktop app and messaging integrations (Telegram, Discord, and others). The model connection is configured the same way.

Does Hermes work with GLM?

Yes, through the OpenAI option: set glm-5.3 or glm-5.3-flash as the model. Note that GLM has a 128K-token context versus 1M for Claude and GPT. For the current model list, use GET https://api.zukko.pro/v1/models or the Models↗ page in your dashboard.

A short setup cheat sheet is in the Zukko docs for Hermes↗.