Hermes Agent custom API: providers, transports and first-call checks

A Hermes Agent custom endpoint is configured outbound, as a named entry under providers: in ~/.hermes/config.yaml, where api is the base URL and transport is the wire protocol. That is a different thing from Hermes' own API server, which points the other way. Both are called “the Hermes custom API” in search results, and the official documentation pages for each rank for the same queries — so fix the direction first.

This page is about Hermes Agent, the open-source agent from Nous Research. A check of the GitHub API on September 21, 2026 returned archived: false, disabled: false, an MIT license and a push the same day; the newest published release is Hermes Agent v0.21.3, tagged v2026.9.14 on September 14, 2026, not a prerelease. The surfaces this page takes configuration from are that repository and hermes-agent.nousresearch.com. hermes-agent.org covers the same project from a domain outside nousresearch.com and loads Microsoft Clarity analytics (checked September 21, 2026); it is not one of the project's own surfaces, so do not take configuration from it. This is also not Hermes 3 or Hermes 4, the Nous open-weight model family, and not the JavaScript engine of the same name.

Two opposite things called the Hermes custom API

Both rows are quoted from Hermes' own pages, read September 21, 2026: the provider reference and the API server page. One naming wrinkle worth checking in your own install: the API server page documents hermes gateway as the command that runs it, while the CLI reference describes hermes gateway as the messaging-service manager with run, start, stop and status subcommands. Run hermes gateway --help rather than guessing. Everything below is the outbound half.

The minimum outbound configuration

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

KUNAVO_API_KEY=your-key

Field by field, from the provider reference: the config key is providers.<name>, the base URL field is api (with base_url and url accepted as aliases), the credential is key_env, an inline api_key or a key_cmd, and the protocol is transport. The same entry also accepts name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider and enabled: false. Select the entry with model.provider: custom:kunavo, or mid-session with /model custom:kunavo:<model-id>.

Two commands are not interchangeable. hermes model, run outside a chat session, is the full provider setup wizard and the only thing that can add a provider or take a key. /model inside a session only switches between what already exists. For enterprise endpoints issuing short-lived tokens, key_cmd names a command that prints a token on stdout — bare, or as JSON with an access_token field — which Hermes runs and caches until shortly before expiry, and which beats a static api_key or key_env on the same entry.

Pick the transport by hand rather than leaving the field blank

The provider reference lists three accepted values for transport on a custom entry. It also says the hermes model Custom Endpoint wizard now prompts for the protocol explicitly and persists the answer to config.yaml, and that URL-based auto-detection “still happens as a fallback when the field is left blank”. The one detection rule the docs spell out is an /anthropic path mapping to anthropic_messages, which a Kunavo base URL does not match; the rest of the heuristic is not enumerated on any page read here, which is the reason to write the field rather than infer what it would do. Kunavo serves /v1/chat/completions, /v1/messages and /v1/responses, so each transport has a matching route on paper.

The Anthropic row deserves the caveat rather than a confident answer. Hermes' Azure Foundry guide states that /v1 is stripped from the base URL because the Anthropic SDK appends /v1/messages to every request — but that sentence sits under an Azure heading, and the provider reference's own example (api: https://proxy.example.com/anthropic) never says what suffix Hermes appends for a generic proxy. So both candidates above are plausible and one of them may produce a double-/v1 404. Check the request path your first call actually records; the base-URL doc covers the origin-versus-/v1 trap behind most 404s on this wire. Authentication is the lesser worry: Kunavo's Messages route accepts both Authorization: Bearer and x-api-key, so whichever header the Anthropic SDK sends for a generic proxy should be accepted — but Hermes does not document that choice, so “should” is the honest word.

One open question this page will not answer either way. Hermes documents a silent upgrade of GPT-5.x-family model names to codex_responses even when config.yaml still says chat_completions — but that sentence appears under provider: azure-foundry while being phrased as a model-name detection. Whether a GPT slug on provider: custom triggers the same move is not documented. If you pick a GPT-class model, record which route the first call went to.

What a custom endpoint does not get for free, per transport

None of these are plan gates. Hermes Agent is “free and open source under the MIT license” per the project's own homepage FAQ, and the providers: dict is documented as ordinary configuration rather than a tier feature. They are capability gates, and they differ by wire.

Two escape hatches for a gateway specifically. catalog_provider accepts a Hermes provider id or a models.dev id and makes the entry's models inherit that catalogue's metadata — lookups only, requests still go to your api URL with your key. And discover_models: false skips the /models probe entirely and uses only the models you listed on the entry, which is the fix when discovery is noisy or slow. Whether Kunavo's /v1/models response satisfies Hermes' probe has not been tested here; if it does not, context detection falls through to that 128K default. The cost reasoning behind these settings — auxiliary slots, delegation workers and cache continuity — is on Hermes Agent pricing rather than repeated here.

A verification ladder to run before you move real work

These are steps for you to run with the observation to expect, not results Kunavo obtained. No Hermes run against Kunavo has been performed, there is no Kunavo setup guide for Hermes, and nothing on this page should be read as a tested integration. Keep your working route available throughout.

1. Add the provider, then diagnose. hermes model adds it; hermes doctor is documented as diagnosing config and dependency issues, and the CLI reference records two custom-endpoint config checks it runs — a custom_providers key that is not a YAML list, and a legacy list entry with no matching providers: entry. Both are warn-only and --fix does not rewrite them.
2. Confirm the key is loaded before spending anything. hermes dump prints a copy-pasteable setup summary — version, provider, model and whether an API key is present. Expect your model id and a present key. hermes prompt-size runs offline and reports a byte breakdown of the system prompt and tool schemas, which is the fixed part every turn carries before any conversation content.
3. One non-streaming text turn. Expect a reply, and expect the request to have gone to the path you intended. A custom endpoint that “works” but returns garbage is a row in Hermes' quickstart troubleshooting table, which names a wrong base URL, a wrong model name or an endpoint that is not actually OpenAI-compatible, and tells you to verify the endpoint in a separate client first.
4. One streaming turn. Expect incremental output rather than one block at the end. Whether a given endpoint's stream framing satisfies Hermes' progress parsing is not something this page tested.
5. One tool round. Expect the tool to execute. If the call is printed as text instead, that is the serving side's tool-calling support, not the transport.
6. Read the meter. /usage is the in-session token, cost and context panel. Reconcile it against the charge your provider account actually recorded — an agent's own arithmetic over reported tokens is an estimate, not a ledger. See the usage doc.

What the ladder costs, and what a mid-session switch costs

Assume the six steps above send 26,000 input tokens and receive 1,150 output tokens in total — a fixed system prompt and tool schema on each of three calls, plus a tool result re-sent once. That assumption is for illustration; hermes prompt-size reports your own fixed prompt as a byte breakdown, which is closer to the truth than a number this page can guess. Rates are live Kunavo catalog prices per million tokens.

This is illustrative token arithmetic at catalog rates, not a measured Hermes task and not a bill ceiling. It excludes cache writes, external tools and tax. The point of the number is its smallness: verifying a route costs far less than discovering a misconfiguration after a week of scheduled work.

The second number is the one the /model command hides. Prompt caches are keyed to the model serving the request, so any mid-conversation model change makes the next message re-read the whole conversation at full input price instead of the cached rate, which Hermes describes as roughly 75 to 90 percent cheaper. On a 120,000-token conversation with Claude Sonnet 5, the difference between $2.00 per million and the $0.20 cache-read rate is about $0.216 for that one turn — trivial once, and not trivial as a habit. Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost times the applicable markup. The minimum is a $10 prepaid top-up with no subscription. See billing.

Backing the configuration out again

Hermes documents an undo path, which is the reason a trial is low risk. enabled: false on the entry hides it without deleting it. Point-in-time copies of config.yaml are written to backups/config/config.yaml.<reason>.<timestamp> before hermes setup or hermes migrate rewrite it and whenever it parses, with identical repeats skipped and only the newest five per reason kept; if the file later fails to parse, Hermes serves the newest good copy instead of built-in defaults. The configuration reference also annotates model.base_url as “cleared on provider switch”, so switching back to a built-in provider is documented as dropping the stale base URL rather than leaving it in the file — check the written value afterwards rather than assuming it.

Three traps come from older tutorials. The legacy top-level custom_providers: list still works and hermes update auto-migrates it into the providers: dict, where legacy model becomes default_model and legacy api_mode becomes transport. LLM_MODEL in .env has been removed outright — config.yaml is the single source of truth. And OPENAI_BASE_URL is documented two ways by two current official pages: the provider reference says it is honored only for the openai-api provider, while the environment-variables reference lists it as the base URL for a custom endpoint. That disagreement is unresolved, so configure the endpoint in config.yaml and do not rely on that environment variable as the route.

If you are choosing a provider rather than wiring one, OpenAI-compatible API covers what the compatible surface does and does not include, and Hermes vs OpenClaw compares the two agents. When you are ready to test this route with a funded key, create a Kunavo account.

FAQ

Hermes Agent documentation — the provider reference, the API server page, the model-configuration page, the configuration page, the CLI reference, the slash-command reference, the quickstart and the project homepage — read September 21, 2026. Repository state and the latest release were checked against the GitHub API the same day. Kunavo's three API routes were confirmed in its own source. Every dollar figure is illustrative token arithmetic over live catalog rates, not a measured task cost. Hermes configuration is reported from source documents; no Hermes run against Kunavo has been performed.