config.yaml, .env and the precedence rule
Configuration is split across two files, and the split is not arbitrary:
- `~/.hermes/config.yaml` — everything that is not a secret: model, terminal backend, compression, memory limits, approval policy
- `~/.hermes/.env` — the secrets: API keys, bot tokens, passwords
The reason is practical: config.yaml can go into a repo, be shared with a team and versioned; .env must never reach version control and is redacted automatically in logs.
When a value is resolved, precedence runs top to bottom:
- CLI arguments — a per-invocation override
- `config.yaml` — the primary settings
- `.env` — a fallback source
- built-in defaults — safe standard values
In a corporate environment there is one more layer above all of this: values pinned system-wide by an administrator. We open that up in the Security stage.
| Command | What it does |
|---|---|
| `hermes config` | Shows the current settings |
| `hermes config get KEY` | Prints the resolved value of one key |
| `hermes config set KEY VAL` | Writes the value to the right file: keys to `.env`, the rest to `config.yaml` |
| `hermes config edit` | Opens `config.yaml` in your editor |
| `hermes config check` | Checks for missing options |
| `hermes config migrate` | Interactively adds missing options |
Inside config.yaml you can reference environment variables with ${VAR_NAME}. That is the right way to share a configuration without putting a key into the YAML. If the variable is undefined, the placeholder stays verbatim and a warning is logged — so the mistake is not swallowed silently, but it does not fix itself either.
Practice. In config.yaml reference an auxiliary model's key as ${GOOGLE_API_KEY}, and put the key itself into .env with hermes config set. Then check the value resolves with hermes config get, and confirm no secret is left in the YAML with grep -r "sk-" ~/.hermes/config.yaml. Done means: the grep comes back empty and the agent works.
📚 Sources and documentation
- Configuration referenceofficialhermes-agent.nousresearch.com
Every section, key and default value.
- Managed scope (administrator configuration)officialhermes-agent.nousresearch.com
The layer above, for pinning values across a company.
- CLI command referenceofficialhermes-agent.nousresearch.com