Understanding Hermes Configuration: config.yaml and .env

Configuration is where a generic agent becomes your agent, and Hermes keeps the surface area manageable: most of the day-to-day settings live in config.yaml, while secrets and overrides come through environment variables and a secrets system. This guide walks through how those pieces fit together so you know where to look when something needs to change.

The Center of It All: config.yaml

The configuration documentation treats config.yaml as the hub for a handful of concerns you will touch constantly:

• Providers and models — which inference backends you use and which models they serve.
• API keys — where credentials for those providers are wired in.
• The settings that govern how the agent runs and who it talks to.

If you use the recommended Nous Portal route, a single subscription covers 300+ frontier models plus the Tool Gateway, which keeps provider configuration light — one account instead of a pile of keys. But Hermes is not tied to any one vendor: it works with Nous Portal, OpenRouter, OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint, and you configure whichever you use.

Environment Variables and a .env-style Workflow

Alongside config.yaml, Hermes reads a complete set of environment variables — the reference documentation lists every variable the agent uses. This is the natural place for values you do not want hard-coded in a committed config file. The common pattern is to store credentials and overrides in a .env-style file and let the agent load them at startup, keeping sensitive values out of your main config and version control.

This separation matters. Config files are easy to share and diff; secrets are not. Keeping the two apart is a good default hygiene habit from day one.

Secrets, Managed Scope, and Locking Things Down

For anything sensitive, Hermes has a dedicated secrets system rather than expecting you to paste keys everywhere. It even includes integrations and docs for real secret managers like 1Password, Bitwarden, and a command-helper secret source, so you can pull credentials from a manager you already trust.

There is also a managed scope concept worth knowing early: an administrator can pin configuration and secrets in a system-level managed directory that users cannot change or override. If you run Hermes in a team or production setting, this is how you keep critical settings immutable and controlled from a single place.

Tools to Manage It All

You are not expected to hand-edit everything. The Hermes web dashboard is a browser-based administration panel for managing configuration, API keys, MCP servers, messaging pairing, webhooks, memory, credentials, and more. There is also a configuration-relevant "which file does what" map covering files like SOUL.md, USER.md, MEMORY.md, and AGENTS.md, which explains who writes each file and when the agent actually sees it — useful for understanding what is config versus what is memory.

A Practical First Config

A sensible starting point: put your provider and model choice in config.yaml, drop your API keys into a secrets source or environment variables, and verify a quick conversation. From there, tune incrementally — add profile-specific config for different personas, set up provider routing, or enable fallback providers so a primary model going down never stalls you.

Key Takeaways

• config.yaml is the hub for providers, models, API keys, and runtime settings.
• Environment variables and a .env-style workflow keep secrets and overrides out of your main config.
• For sensitive credentials, use the secrets system and managers like 1Password or Bitwarden.
• Managed scope lets an administrator pin immutable config and secrets for team and production use.