This page covers the detailed mechanics of configuration management and setup in Hermes Agent. It explains the layered configuration hierarchy that governs runtime settings, describes the interactive setup wizard, and presents key configuration files integral to the system initialization and environment control.
Hermes stores all configuration and runtime data in a well-defined user directory, by default ~/.hermes/. This home directory is configurable via the HERMES_HOME environment variable hermes_cli/config.py124-128
The directory structure is automatically created when the Hermes Agent initializes via the ensure_hermes_home function hermes_cli/config.py149 and consists of:
| Path | Purpose |
|---|---|
config.yaml | Main structured configuration (model, terminal, tools, etc.) hermes_cli/config.py5 |
.env | Secrets and API keys (e.g., OPENROUTER_API_KEY) hermes_cli/config.py6 |
auth.json | OAuth credentials (managed via hermes_cli/auth.py) hermes_cli/auth.py5-6 |
SOUL.md | Primary agent persona (slot #1 in system prompt) website/docs/user-guide/configuration.md22 |
memories/ | Persistent memory files (MEMORY.md, USER.md) website/docs/user-guide/configuration.md23 |
skills/ | Agent skills (managed via skill_manage tool) website/docs/user-guide/configuration.md24 |
cron/ | Scheduled jobs configuration website/docs/user-guide/configuration.md25 |
sessions/ | Message gateway session storage website/docs/user-guide/configuration.md26 |
logs/ | Log files (errors.log, gateway.log, agent.log) website/docs/user-guide/configuration.md27 |
Sources: hermes_cli/config.py1-32 hermes_cli/auth.py1-17 website/docs/user-guide/configuration.md9-28
Hermes Agent applies settings in a layered precedence order to determine runtime behavior. The resolution order (highest priority first) is:
--model or --provider override all other sources for a single invocation website/docs/user-guide/configuration.md57~/.hermes/config.yaml: The primary config file for non-secret settings website/docs/user-guide/configuration.md58~/.hermes/.env: Fallback for environment variables; strictly required for secrets (API keys) website/docs/user-guide/configuration.md59DEFAULT_CONFIG hermes_cli/setup.py139-140Configuration Priority and Resolution
hermes config set command automatically routes values: API keys are identified and saved to .env via save_env_value, while settings go to config.yaml website/docs/user-guide/configuration.md49-51config.yaml supports ${VAR_NAME} syntax to reference variables, handled during config loading website/docs/user-guide/configuration.md73-86config.yaml fails to parse, Hermes snapshots the corrupted file to config.yaml.corrupt.<ts>.bak before falling back to defaults hermes_cli/config.py44-95providers.<id>.request_timeout_seconds override legacy environment variables like HERMES_API_TIMEOUT website/docs/user-guide/configuration.md90-96gateway/config.py which coerces types for transport tokens and systemd watchdog intervals gateway/config.py77-190Sources: hermes_cli/config.py44-154 website/docs/user-guide/configuration.md49-96 run_agent.py119-132 gateway/config.py1-207
config.yaml ReferenceThe config.yaml file governs the structured behavior of the agent website/docs/user-guide/configuration.md9
| Section | Description | Key Configuration Keys |
|---|---|---|
model | AI model & provider routing | default, provider, base_url cli-config.yaml.example8-48 |
terminal | Terminal execution backend | backend, cwd, timeout, env_passthrough website/docs/user-guide/configuration.md120-125 |
agent | Agent loop heuristics | reasoning_effort, max_turns hermes_cli/setup.py119-132 |
auxiliary | Side-task specialized models | vision, compression, web_extract agent/auxiliary_client.py3-41 |
updates | Update and backup behavior | pre_update_backup, backup_keep website/docs/user-guide/configuration.md100-107 |
gateway | Messaging gateway settings | multiplex_profiles, platforms gateway/config.py48-74 |
Sources: website/docs/user-guide/configuration.md98-128 cli-config.yaml.example8-142 agent/auxiliary_client.py1-41 gateway/config.py1-25
The .env file stores sensitive API keys and environment-specific overrides hermes_cli/config.py6
| Environment Variable | Purpose |
|---|---|
OPENROUTER_API_KEY | Recommended for multi-model access cli-config.yaml.example45 |
ANTHROPIC_API_KEY | Native Anthropic access cli-config.yaml.example18 |
GOOGLE_API_KEY | Google AI Studio / Gemini access cli-config.yaml.example21 |
HF_TOKEN | Hugging Face Inference Providers token cli-config.yaml.example26 |
HERMES_HOME | Overrides the default ~/.hermes directory hermes_cli/main.py124 |
TERMINAL_ENV | Sets the execution backend (e.g. docker, local) run_agent.py82 |
Sources: hermes_cli/config.py1-15 cli-config.yaml.example13-33 hermes_cli/main.py123-128 run_agent.py68-90
The hermes setup command launches a modular interactive wizard hermes_cli/main.py14 It is defined in hermes_cli/setup.py and handles model selection, provider authentication, and tool configuration.
Setup Wizard Data Flow
Sources: hermes_cli/setup.py1-13 hermes_cli/main.py1-44 hermes_cli/config.py143-145 hermes_cli/tools_config.py92-121
Hermes supports multiple execution environments via the terminal.backend setting website/docs/user-guide/configuration.md115 The backend determines where tools like terminal or execute_code run.
| Backend | Environment | Implementation Detail |
|---|---|---|
local | Your machine directly | Default shell execution website/docs/user-guide/configuration.md131 |
docker | Containerized | Single persistent container website/docs/user-guide/configuration.md132 |
ssh | Remote Server | Network boundary via SSH website/docs/user-guide/configuration.md130 |
modal | Cloud Sandbox | Ephemeral cloud compute website/docs/user-guide/configuration.md127 |
daytona | Managed Cloud | Daytona workspace integration website/docs/user-guide/configuration.md128 |
singularity | HPC Container | Secure namespaces/Apptainer website/docs/user-guide/configuration.md126 |
Sources: website/docs/user-guide/configuration.md115-132 cli-config.yaml.example120-128 run_agent.py68-90
| Command | Action |
|---|---|
hermes config | View current effective configuration hermes_cli/config.py9 |
hermes config set KEY VAL | Update a setting (routes to .env or config.yaml) hermes_cli/config.py12 |
hermes config get KEY | Print a resolved configuration value hermes_cli/config.py11 |
hermes config edit | Opens config.yaml in the system editor hermes_cli/config.py10 |
hermes config wizard | Re-run the interactive setup wizard hermes_cli/config.py14 |
hermes config unset KEY | Remove a user configuration value hermes_cli/config.py13 |
Sources: hermes_cli/config.py1-15 website/docs/user-guide/configuration.md32-47
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.