Model Providers & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
The Model Providers and Authentication system enables Hermes Agent to interact with diverse Large Language Model (LLM) providers while maintaining secure credential management. This architecture supports provider-agnostic workflows. It rotates credential pools across multiple API keys automatically to ensure continuous operation.
The system separates configuration settings from sensitive secrets. It uses specific files for environment variables, OAuth tokens, and global settings. This modular approach allows users to swap models and providers mid-workflow without re-authenticating or restarting the agent. Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:15-30, agent/learn_prompt.py:28-35
Authentication Mechanics
Hermes Agent employs a multi-layered authentication strategy. It distinguishes between static API keys, dynamic OAuth tokens, and identity-shaping profiles.
Credential Hierarchy and Storage
The agent resolves credentials using a prioritized path system. Sensitive data resides in the .env file or an auth.json file. The system enforces strict privacy standards. It prevents environment-derived usernames or login details from leaking into shared skills.
This diagram illustrates the logic the agent follows to resolve credentials before communicating with a provider.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:65-75, agent/learn_prompt.py:35-42
Key Authentication Files
| File Path | Description | Security Level |
|---|---|---|
~/.hermes/config.yaml | Main configuration for settings. It never contains secrets. | Low |
~/.hermes/.env | Contains API keys and secrets only. | High (Private) |
~/.hermes/auth.json | Stores OAuth tokens and credential pools for provider rotation. | High (Encrypted/Private) |
~/.hermes/SOUL.md | Defines the agent's identity and communication style. | Medium |
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:67-78, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md:25-30
Provider Abstraction Layer
Hermes Agent interacts with over 20 providers. The abstraction layer ensures that tool-calling and chat interfaces remain consistent regardless of the underlying model.
Supported Providers
The system works with major proprietary and open-source ecosystems:
- Commercial Cloud: OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI.
- Local Models: Direct integration for running models on local hardware.
- OAuth Integration: A local OpenAI-compatible proxy allows third-party apps to use the agent's OAuth provider.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:12-25, skills/autonomous-ai-agents/hermes-agent/SKILL.md:135-140
Identity Management (SOUL.md)
The SOUL.md file serves as the primary identity marker for the agent. It is the first item loaded into the system prompt. It defines the agent's tone, personality, and communication style. Unlike AGENTS.md, which contains project-specific instructions, SOUL.md applies globally to the agent's behavior.
The sequence diagram shows how the agent injects identity from SOUL.md into every provider request.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md:10-20, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md:45-55
Security and Privacy Standards
The authentication system adheres to "Hardline Authoring Standards." These standards protect user privacy during skill creation and model interaction.
- Credential Redaction: The agent must strip credentials, API keys, and secrets from any source content before processing.
- Anonymous Authoring: Skills saved by the agent use the literal value
Hermesas the author. This prevents the leakage of the host machine's username. - Platform Gating: The system identifies if a skill uses OS-bound primitives like
osascript(macOS) orsystemctl(Linux) to ensure proper credential application across different environments.
Sources: agent/learn_prompt.py:35-45, skills/creative/baoyu-infographic/SKILL.md:165-170
Configuration Procedures
To update or verify provider settings, you must use the internal CLI tools rather than manual file editing.
- Configure a Provider: Run
hermes modelto select your preferred provider and model. - Add API Keys: Use
hermes setupto enter credentials. The agent writes these to the.envfile automatically. - Check Status: Execute
hermes doctorto verify provider connectivity and credential validity. - Set Global Options: Use
hermes config set KEY VALto modify non-secret settings inconfig.yaml.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md:55-65, skills/autonomous-ai-agents/hermes-agent/SKILL.md:160-165