Loading

← Hermes Agent Operator Track

Your ~/.hermes home and config.yaml

> All settings live under ~/.hermes/ — learn the map before you edit YAML by hand.

Canonical: https://www.brainyxai.co.za/education/hermes/configuration-home

Markdown: https://www.brainyxai.co.za/md/education/hermes/configuration-home.md

Course: Hermes Agent Operator Track

Lesson: 3 of 9

Minutes: 16

Author: Brainyx AI

What you will be able to do

  • Locate the Hermes config directory and primary config file
  • Prefer setup wizards before hand-editing YAML
  • Know when to open the official configuration reference

The home directory

Hermes stores settings under `~/.hermes/` for easy access. That directory is your agent’s “home”: config, secrets layout (as documented), sessions, skills, and related state.

Operator rule: treat `~/.hermes/` like production config. Back it up before experiments. Don’t commit API keys to git.

Easiest path to a good config.yaml

You do not need to invent YAML on day one. Official guidance: run `hermes setup --portal` so OAuth populates a working provider + Tool Gateway tools without hand-editing.

Hand-edit when you need:

  • Custom MCP servers
  • Messaging gateway credentials
  • Multiple profiles / gateways
  • Fine-grained tool filters or security policies

Canonical reference: [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration).

Models without the rabbit hole

Use `hermes model` (and the configuring-models docs) when switching providers. Portal subscribers may get bundled tools and billing perks — see [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal).

Sessions and profiles (preview)

  • Sessions — persistence, resume, search, per-platform tracking ([Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions))
  • Profiles — run multiple agents with isolated config ([Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles))
  • Git worktrees — parallel agents on one repo safely ([Git Worktrees](https://hermes-agent.nousresearch.com/docs/user-guide/git-worktrees))

You’ll use these when one agent identity isn’t enough (e.g. “ops bot” vs “coding agent”).

Docker & remote backends

Hermes supports multiple terminal backends (local, Docker, SSH, Daytona, Singularity, Modal). Start local; move to Docker/SSH when you need isolation or a remote machine. See [Docker](https://hermes-agent.nousresearch.com/docs/user-guide/docker) when you’re ready.

Config map lab

1. List the top-level contents of ~/.hermes/ (or the Windows equivalent path from the docs).

2. Open config.yaml in a read-only editor and note provider/model and any mcp_servers blocks — do not paste secrets into chat logs.

3. Change nothing yet; write down one intentional change you’ll make after the Tools lesson.

Checkpoints

  • I can find my Hermes home directory
  • I prefer setup commands over blind YAML edits

Read the map before editing the territory

The configuration home holds several distinct kinds of state, and they deserve different treatment. Settings define behaviour and are safe to version. Credentials must never enter version control. Memory and skills are accumulated state you would be annoyed to lose. Logs are diagnostic and disposable.

Knowing which category a file falls into answers most operational questions: what to back up, what to commit, what to delete when troubleshooting, and what to copy when moving machines.

Safe editing practice

YAML is unforgiving in specific ways — indentation is semantic, a stray tab breaks parsing, and a quoted value that should be a boolean fails quietly rather than loudly.

Three habits prevent the common failures. Copy the file before editing, so reverting is one command. Change one thing at a time and verify the agent still responds, so you always know what broke it. Prefer setup wizards and CLI commands over hand-editing for anything they cover, because they validate input.

When the agent stops working after a config change, revert to your copy first and reintroduce the change deliberately. Debugging forward from a broken state is slower than resetting to a known-good one.

Version control without leaking secrets

Keeping configuration in git is genuinely useful — you get history, diffs, and recovery. It is also the most common way people publish API keys.

Keep secrets in environment variables or a separate ignored file, commit the structure rather than the values, and confirm your ignore rules actually work before the first push rather than after. If a key does reach a repository, rotate it — deleting the commit is not sufficient.

Shared and multi-user machines

On a shared workstation, the configuration home is readable by anyone with access to that account. Verify file permissions, do not run the agent under a shared login, and remember that accumulated memory may contain business context you would not hand to a colleague wholesale.

Mini-FAQ

A: Configuration, skills, and memory. Logs and caches regenerate.

A: Yes, and it is convenient — but exclude credentials and be deliberate about whether accumulated memory should travel with you.

A: Almost always indentation or a type mismatch. Restore your copy and reapply the change one line at a time.

Next lesson

Continue to [CLI and daily use](https://www.brainyxai.co.za/education/hermes/cli-and-daily-use).

Official reference: https://hermes-agent.nousresearch.com/docs/user-guide/configuration

Course hub: https://www.brainyxai.co.za/education/hermes · Previous: https://www.brainyxai.co.za/education/hermes/install-and-setup · Next: https://www.brainyxai.co.za/education/hermes/cli-and-daily-use

Return to the course hub, or explore Brainyx AI services to put the skill into a live system. Markdown: /md/education/hermes/configuration-home.md

Book a consultation · joshua@brainyxai.co.za · Markdown mirrors