Hermes Agent configuration

Where Hermes Agent configuration lives

One directory holds the whole installation state:

~/.hermes/
├── config.yaml     # non-secret settings: model, terminal, compression, memory, skills
├── .env            # API keys, tokens, and other secrets
├── auth.json       # OAuth credentials created by login flows
├── SOUL.md         # agent identity and personality
├── memories/       # MEMORY.md and USER.md
├── skills/         # installed and agent-authored skills
├── cron/           # scheduled jobs
├── sessions/       # gateway and chat sessions
└── logs/           # agent, gateway, and error logs

The location varies by platform, not the layout:

Configuration precedence and scope

When the same setting is defined more than once, the highest source wins:

The rule of thumb the documentation gives is worth keeping: secrets in .env, everything else in config.yaml. Profiles scope a whole configuration set, so one installation can hold several isolated setups without cross-talk.

Back up and redact before editing

Do these two things before your first edit, not after your first mistake.

When sharing configuration for support or review, redact every secret. A shareable snippet looks like this:

model:
  provider: openrouter
  name: <model-id>

terminal:
  backend: local
  timeout: 180

# secrets stay in ~/.hermes/.env, never in config.yaml
# OPENROUTER_API_KEY=<redacted>

If you need a profile copy without credentials, hermes profile export is the documented path.

Where model and provider settings live

Model selection sits in config.yaml; the credential that makes it work sits in .env.

model:
  provider: openrouter   # provider identifier
  name: <model-id>       # provider-specific model identifier

# ~/.hermes/.env
OPENROUTER_API_KEY=<redacted>

Auxiliary work — vision analysis, context compression, title generation — can be routed to a separate, usually cheaper model under an auxiliary: block, and per-provider timeouts live under providers:.

Which provider to choose, which model identifier format each provider expects, and how to verify the connection are a different decision. That belongs to model and provider settings.

Where tool, interface, and profile settings live

The blocks you are most likely to touch early:

• terminal: — execution backend (local, docker, ssh, and cloud sandboxes), working directory, per-command timeout, and container CPU, memory, and disk limits.
• approvals: — approval mode and deny rules for dangerous commands.
• memory: — enable flags, character limits, and whether memory writes require approval.
• skills: — external skill directories, the agent-write approval gate, and the content guard.
• mcp_servers: — one block per Model Context Protocol server, with its transport and environment.
• compression: and agent: — context-compression thresholds and run budgets.
• updates: — pre-update backup behaviour and how many backups to keep.

Profiles keep several such configurations side by side; hermes profile manages them.

Environment variables and secret references

Two mechanisms, and they are easy to confuse:

1. Secrets in .env. API keys and tokens go here. The file is treated as sensitive and kept out of logs. Restrict it: chmod 600 ~/.hermes/.env.
2. References inside config.yaml. A ${VAR_NAME} placeholder is substituted from the environment, so a non-secret file can point at a secret value:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}

Undefined variables are left verbatim and logged as a warning, which is a useful signal that a reference never resolved.

hermes config set writes to the right file for you — recognised secret keys are routed into .env rather than into config.yaml.

Where those secrets are then allowed to travel — into containers, into MCP subprocesses, into skills — is a security decision, covered by credential handling.

Validate configuration

Reading a resolved value is the fastest way to answer "why is it not using what I set" — it shows the winner, not your intention. For a broader sweep across dependencies, backends, and provider authentication, run hermes doctor.

Reset or migrate settings

• Add options introduced by a newer release: hermes config migrate walks through what is missing.
• Remove a single override and fall back to the default: hermes config unset KEY.
• Rewrite retired model names or deprecated settings: hermes migrate.
• Start clean without losing credentials: back up first, then move config.yaml aside and re-run setup. Keep .env and auth.json if you want to preserve authentication.
• Restore a previous state: hermes import restores a backup archive.

Updates take a pre-update snapshot of state by default, and how many snapshots to keep is itself configurable under updates:.

Route configuration failures

If a setting will not take effect, resolve it in this order: check the resolved value with hermes config get, confirm the source that wins precedence, then run hermes config check. If the failure is not obviously configuration — an authentication error, a model error, a tool error — take it to configuration troubleshooting rather than editing more keys.