This page documents the authentication system that enables Hermes Agent to connect to Large Language Model (LLM) inference providers. It covers the provider registry, OAuth flows, API key management, credential storage, provider resolution logic, and the auto-detection system.
Scope: This page focuses on authentication and provider selection for the primary inference provider. For information about auxiliary models used by tools (vision analysis, web scraping, context compression), see Auxiliary Client (4.5)
Hermes Agent supports a wide range of inference providers through a unified authentication system that handles:
CredentialPool system agent/credential_pool.py1-35Hermes Agent maintains a provider registry via the PROVIDER_REGISTRY dictionary defined in hermes_cli/auth.py, containing ProviderConfig dataclasses that describe each known provider's authentication type, base URLs, and environment variables for API keys hermes_cli/auth.py167-220
Additionally, the providers module contains ProviderProfile classes that define runtime behavior, such as reasoning configuration and model-specific parameters providers/base.py1-15
| Provider ID | Auth Scheme | Env Vars / Keys | Notes |
|---|---|---|---|
nous | OAuth Device | N/A | Nous Portal preferred models hermes_cli/auth.py168-176 |
openai-codex | OAuth Ext | N/A | Uses app_EMoamEEZ73f0CkXaXp7hrann hermes_cli/auth.py177-182 |
anthropic | API Key | ANTHROPIC_API_KEY | Direct Anthropic API hermes_cli/auth.py206-211 |
openrouter | API Key | OPENROUTER_API_KEY | hermes_cli/auth.py212-217 |
xai-oauth | OAuth Device | N/A | xAI Direct OAuth models hermes_cli/auth.py196-200 |
minimax | OAuth Device | N/A | MiniMax global hermes_cli/auth.py183-189 |
minimax-cn | OAuth Device | N/A | MiniMax China hermes_cli/auth.py190-195 |
qwen-oauth | OAuth Ext | N/A | Alibaba Qwen hermes_cli/auth.py201-205 |
copilot | API Key | GITHUB_TOKEN | GitHub Copilot / GitHub Models hermes_cli/auth.py218-220 |
Sources: hermes_cli/auth.py161-220 providers/base.py1-15
Hermes uses a resolution chain to determine which provider and credentials to use at runtime. This chain handles the fallback from requested providers to the auto-detection of active credentials.
resolve_provider(requested: Optional[str]) -> str: Determines the preferred provider ID based on explicit request, config.yaml, or detected active provider hermes_cli/auth.py440-460load_pool(provider: str) -> CredentialPool: Loads credential pools from ~/.hermes/auth.json (inside the credential_pool key) to support rotation agent/credential_pool.py38-41resolve_runtime_provider(requested_provider: Optional[str]) -> dict: Central entry point for resolving final API keys, tokens, and endpoints hermes_cli/runtime_provider.py237-331The resolution logic prioritizes active sessions and explicit configurations before falling back to environment-based detection.
Figure: Runtime Provider Resolution Flow Sources: hermes_cli/runtime_provider.py237-331 agent/credential_pool.py38-41 hermes_cli/auth.py440-460
The CredentialPool system enables failover and rotation across multiple keys for the same provider agent/credential_pool.py1-15
Users can configure rotation strategies in config.yaml via the credential_pool_strategies key agent/credential_pool.py106-115:
fill_first: Use the highest priority available entry until exhausted agent/credential_pool.py106round_robin: Rotate through all available entries agent/credential_pool.py107random: Select an entry at random agent/credential_pool.py108least_used: Select the entry with the fewest uses agent/credential_pool.py109The pool tracks the status of each PooledCredential agent/credential_pool.py165-185:
STATUS_OK: Credential is functional.STATUS_EXHAUSTED: Credential is rate-limited or out of quota agent/credential_pool.py66STATUS_DEAD: Credential has a permanent failure (e.g., revoked OAuth token) agent/credential_pool.py73Exhausted credentials cool down for a duration based on the error code (e.g., 5 minutes for 401, 1 hour for 429) before being retried agent/credential_pool.py121-123
Sources: agent/credential_pool.py1-185
Implemented in _login_nous() and similar handlers, this flow fetches a user_code and verification_uri from the provider. The CLI then polls the token endpoint until the user authorizes the device in their browser hermes_cli/auth.py750-845
resolve_codex_runtime_credentials() handles token retrieval and refresh for the openai-codex provider hermes_cli/auth.py1047-1064resolve_qwen_runtime_credentials() supports Alibaba Qwen authentication by reading from the Qwen CLI's local credential file hermes_cli/auth.py1065-1081resolve_gemini_oauth_runtime_credentials() supports Cloud Code Assist authentication hermes_cli/auth.py1104-1121resolve_api_key_provider_credentials() scans os.environ (via profile-scoped _getenv) for keys defined in the ProviderConfig.api_key_env_vars list hermes_cli/auth.py613-644
Sources: hermes_cli/auth.py613-1121
Hermes can dynamically inject credentials from external secret managers during environment loading hermes_cli/env_loader.py32-38
The load_hermes_dotenv() function calls _apply_external_secret_sources(), which populates os.environ with secrets from configured backends hermes_cli/env_loader.py43-50 These "borrowed" secrets are tracked in _SECRET_SOURCES to explain their origin in the UI (e.g., "from Bitwarden") hermes_cli/env_loader.py32-38 hermes_cli/env_loader.py89-113
To prevent authentication failures due to copy-paste corruption, Hermes automatically strips non-ASCII characters from environment variables ending in _API_KEY, _TOKEN, _SECRET, or _KEY hermes_cli/env_loader.py131-163
Sources: hermes_cli/env_loader.py1-163 agent/secret_sources/bitwarden.py1-10 agent/secret_sources/command.py1-10
| Location | Entity | Purpose |
|---|---|---|
~/.hermes/auth.json | AuthStore | Persistent OAuth tokens and credential_pool state hermes_cli/auth.py6-10 |
~/.hermes/.env | Env Vars | API keys for providers like OpenRouter and Anthropic hermes_cli/config.py6 |
~/.hermes/config.yaml | Config | User preferences and model overrides hermes_cli/config.py5 |
Access to auth.json is protected by file locking (_auth_store_lock) using fcntl on Unix or msvcrt on Windows to prevent data corruption during concurrent access by the CLI and Gateway hermes_cli/auth.py53-61
Figure: Association of Storage Files to Code Loaders Sources: hermes_cli/auth.py6-71 agent/credential_pool.py38-41 hermes_cli/config.py5-6 hermes_cli/env_loader.py11-13
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.