Provider Runtime Resolution and Credential Isolation

Hermes uses a shared runtime resolver so CLI, gateway, cron, ACP, API, and auxiliary tasks can agree on which provider, endpoint, credential, and API protocol should handle a request.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/provider-runtime

Resolution contract

The resolver returns a provider identity, API mode, base URL, credential, and source. API mode is critical: an OpenAI-compatible chat endpoint, Codex Responses route, and native Anthropic Messages route need different request and response handling even when the user asks for the same model behavior.

Credential isolation is a safety boundary. A key selected for one provider must not be reused against an unrelated custom base URL. Saved provider and model choices also need predictable precedence so a stale shell variable cannot silently redirect a normal session.

Routing checklist

• Record the requested provider and model separately.
• Confirm the resolved API mode matches the endpoint protocol.
• Bind each credential to its intended base URL.
• Verify custom providers do not inherit unrelated keys.
• Configure auxiliary tasks deliberately when they differ from main chat.
• Define fallback order and acceptable model changes.
• Expect cache changes after provider or credential rotation.
• Test CLI, gateway, and cron paths that rely on the same resolver.

Pitfalls

• Treating every OpenAI SDK client as the same protocol.
• Letting a general environment key leak to a custom endpoint.
• Verifying only the interactive model picker, not the runtime result.
• Forgetting that auxiliary vision or compression can use a separate route.
• Adding fallback without testing tool-call parity and context limits.

Verification steps

1. Select a disposable provider-model pair through the supported model flow.
2. Inspect the resolved provider, API mode, and base URL without printing credentials.
3. Run a text-only smoke request.
4. Run one harmless tool call through the same route.
5. Test an auxiliary task and confirm its configured route.
6. Simulate a retryable primary failure in a controlled environment.
7. Confirm fallback uses the intended credential and record the cache and behavior change.