You called your relay `Anthropic` — and it got sent the official key


You added a relay endpoint to config.yaml to cut costs, and named it the obvious thing: OpenRouter, because that is the API it forwards. Two weeks later the bill has not moved and the relay operator sends you a message: why did your official key show up on my server? You check the config. The base_url clearly points at their domain.

You did not fat-finger a character. The problem was who the name belonged to. When a providers: key collides with a built-in provider name, the model-switch path and the path that actually sends the request used to reach different conclusions: one validated your endpoint, the other sent to the built-in host with the built-in credential. Two code paths, two answers, and something fell through the gap between them.

One name collision, two diverging paths

providers: is where you declare your own endpoint in config:

providers:
  OpenRouter:
    base_url: https://relay.example.com/v1
    key_env: RELAY_API_KEY
    default_model: some-model

In the normal case, /model switching, a dashboard save, and the next turn’s actual request should all point at the same endpoint with the same key. A colliding name pulled that apart.

Since #151042, resolve_user_provider matched providers: keys case-insensitively, so Anthropic: and OpenRouter: started hitting the user’s entry. The switch path then did this: /model validated your endpoint and saved model.provider: Anthropic. On the next turn the runtime canonicalised the bare built-in name onto the built-in provider (_select_named_custom_provider → _shadowed_by_builtin), so the request went to api.anthropic.com — carrying your built-in key.

With OpenRouter it was worse in a different way: the request did go to your URL, but it carried OPENROUTER_API_KEY. That is the key the relay operator saw.

The fix: one predicate, read by three call sites

The maintainer ruling was “the user entry wins”, and it is stated precisely:

A bare provider name in any case (openrouter, OpenRouter, anthropic, Anthropic, deepseek, …) whose providers: entry, keyed under that name, declares its own base_url, means the user’s entry. A same-named block with no endpoint — tuning only — keeps the built-in.

That rule lives in one function, builtin_name_user_entry() in hermes_cli/runtime_provider_custom.py:

def builtin_name_user_entry(name: str, providers: Any) -> Optional[str]:
    """Config key of the enabled ``providers:`` entry a bare built-in ``name`` routes to, else None.
    The one predicate the switch, the dashboard save and doctor read, so validation and the next
    turn agree: the entry wins when it declares its own base_url (#151775)."""

The phrase that matters is “the one predicate”: switch, dashboard save and doctor read the same decision, so the endpoint that gets validated is always the endpoint the next turn runs on. The persisted identity follows:

def persisted_provider_id(provider: str, providers: Any) -> str:
    owner = builtin_name_user_entry(provider, providers)
    return provider if owner is None else custom_provider_slug(owner, owner)

So /model on the Anthropic key persists custom:Anthropic, and the runtime resolves that identity back to your base_url and your credential. Both sides agree.

The same commit closed a quieter hole: a built-in env/pool key is never sent to a model.base_url that a providers: entry with its own credential owns. That covers the registry api-key path, the pool-entry path and the Anthropic env path. There is one deliberate exception — an entry without a credential keeps the old #10622 mirror behaviour, i.e. “use the built-in key against your own mirror”.

A doctor warning now says it out loud

After the fix, a config like this stops resolving silently in the user’s favour without saying so:

model:
  provider: openrouter
  base_url: https://relay.example.com/v1

providers:
  openrouter:
    base_url: https://relay.example.com/v1
    key_env: RELAY_API_KEY

hermes doctor prints (from _warn_builtin_name_owned_by_entry):

⚠ model.provider 'openrouter' runs on your providers.openrouter endpoint, not the built-in
  (https://relay.example.com/v1)

and offers two ways out: state the identity explicitly with hermes config set model.provider custom:openrouter, or remove providers.openrouter.base_url to use the built-in provider again. The warning is useful because it names both facts you need — the address actually being hit, and the identity you should be using — instead of leaving you to infer them.

What to check on your own machine

If your config.yaml has a providers: section, spend two minutes on three things:

  1. Look at the key names. openai, anthropic, openrouter, deepseek, gemini, xai, lmstudio in any capitalisation count as collisions.
  2. Run hermes doctor and look for the runs on your providers.<key> endpoint warning.
  3. If you genuinely want a built-in name pointed at your own relay, both routes work: write model.provider as custom:<key>, or just rename the key to something like my-relay — the providers: key is only your label.

Conversely, if all you wanted was a longer timeout or an extra header for a built-in provider, do not put base_url in that block. A same-named block without an endpoint keeps built-in semantics, and that escape hatch is explicitly preserved by the ruling.

The real lesson

In a config system, a “name” usually carries three jobs at once: a label for humans, a routing key for the program, and a credential scope. The moment user-chosen names are allowed to overlap with built-in names, those three jobs fight — and the failure mode is rarely an error. It is quietly sending to the wrong place, which is especially bad when the thing being sent is a credential.

It also never shows up on first use, because on the happy path both code paths agree. It only diverges at the moments when identity gets re-derived: switching models, reloading a session, editing config through the dashboard.

Status: on main, not in v0.23.1

PR #152465 merged on 2026-11-10 at 21:26 UTC; the v0.23.1 tag stops at a commit from 11-10 00:24 UTC. The fix is main-only for now — source installs tracking main have it, v0.23.1 and older do not.

Update (2026-11-17): these changes shipped in v0.23.2 (November 16) — hermes update brings them in. The “not in v0.23.1” wording above is a snapshot from publication time.

Until then, the safe move is simply not to name a providers: entry after a built-in provider. Renaming costs nothing functionally; it only costs the comfort of reading your own config.

If you want to go deeper: model overrides covers per-model behaviour switches, secret encryption explains where credentials actually live and how they are unwrapped, and the three new providers walkthrough has real providers: blocks to compare against. On the command side, the config reference and doctor reference are the two pages this change touches directly.