Configuration & Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
Hermes Agent uses a multi-layered configuration system to manage agent behavior, model provider credentials, and system settings. The system separates non-sensitive settings, stored in config.yaml, from sensitive credentials stored in environment variable files. This architecture supports isolated profiles, allowing users to maintain independent configurations and memory stores for different use cases.
The configuration lifecycle involves loading global defaults, applying user-defined overrides from the ~/.hermes directory, and injecting sensitive keys from the .env file into the runtime environment.
Sources: hermes_cli/config.py, skills/autonomous-ai-agents/hermes-agent/SKILL.md
Core Configuration Components
The Hermes configuration system relies on three primary files located within the $HERMES_HOME directory (defaults to ~/.hermes).
File Locations and Purposes
| File | Location | Purpose |
|---|---|---|
config.yaml | ~/.hermes/config.yaml | Main settings, display preferences, and toolsets. Never contains secrets. |
.env | ~/.hermes/.env | Sensitive API keys and provider credentials. |
SOUL.md | ~/.hermes/SOUL.md | Defines agent identity, personality, and communication style. |
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
Data Flow Architecture
The following diagram illustrates how Hermes resolves its configuration at runtime by merging defaults with local user files and environment variables.
Environment Variable Loading
The env_loader.py module manages the discovery and loading of sensitive credentials. It identifies the correct storage path for the .env file based on the HERMES_HOME environment variable. If HERMES_HOME is not set, the loader defaults to the user's home directory under .hermes.
Key behavior includes:
- Path Resolution: The loader checks for a
.envfile at the root ofHERMES_HOME. - Loading Logic: It uses
dotenvto load variables into the process environment if the file exists. - Error Handling: If the directory does not exist or the file is missing, the loader exits without raising an error to allow manual environment configuration.
Sources: hermes_cli/env_loader.py:1-24
Identity and Style via SOUL.md
The SOUL.md file serves as the primary identity marker for the Hermes instance. It is the first item injected into the system prompt. Unlike config.yaml, which handles mechanical settings, SOUL.md governs the agent's tone, personality, and response compacting.
- Global vs. Profile: Hermes uses the global
~/.hermes/SOUL.mdby default. - Priority: Content from
SOUL.mdreplaces the built-in default identity text. - Separation of Concerns: Project-specific rules (e.g., "Use pytest") belong in
AGENTS.md, while universal traits (e.g., "Be direct") belong inSOUL.md.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
Profile Configuration
Hermes supports isolated instances through profiles. Each profile maintains its own subdirectory within ~/.hermes/profiles/<name>/. This structure allows for independent config.yaml, SOUL.md, and session stores.
Profile Directory Structure
Configuration Management via CLI
You can manage config.yaml settings directly through the CLI using the hermes config set command. This ensures proper YAML formatting and prevents file corruption that can occur during manual editing.
- Setting Values:
hermes config set <KEY> <VAL>updates the active configuration. - Theme Management: The
display.skinsetting allows live repainting of the interface. - Skin Overrides: To modify specific colors without forking a theme, use
hermes skin set <key> <hex>.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md
Configuration Parameters
The config_defaults.py file defines the baseline settings for the agent.
| Section | Parameter | Default Value | Description |
|---|---|---|---|
display | interface | cli | Sets the default interface (cli or tui). |
display | skin | default | Defines the active UI theme. |
approvals | mode | standard | Controls user-confirmation for tool calls. |
terminal | cwd | System Home | Sets the default working directory. |
Sources: hermes_cli/config_defaults.py, skills/autonomous-ai-agents/hermes-agent/SKILL.md
Summary
The Hermes Agent configuration architecture ensures a secure and flexible environment by separating identity, settings, and credentials. Through the use of config.yaml, .env, and SOUL.md, the system provides granular control over agent behavior while supporting multi-agent orchestration and profile isolation. Users should prioritize the CLI for configuration changes to maintain file integrity.