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:
- Look at the key names.
openai,anthropic,openrouter,deepseek,gemini,xai,lmstudioin any capitalisation count as collisions. - Run
hermes doctorand look for theruns on your providers.<key> endpointwarning. - If you genuinely want a built-in name pointed at your own relay, both routes work: write
model.providerascustom:<key>, or just rename the key to something likemy-relay— theproviders: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 updatebrings 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.