Tutorial 7: Configuration Files | Easy Understand Hermes Agent

This is part of the Hermes Agent official tutorial series. View all tutorials

Think of your Hermes Agent like a new smartphone — before you start using it, you need to set your wallpaper, choose your ringtone, and add your accounts. Configuration files are where Hermes stores all those “settings” so it knows how you want it to behave every time you run it.

In this tutorial, we’ll walk through where your settings live, how to view and change them, and the easiest way to get everything working without touching a single line of YAML (that’s just a simple text format for settings).

Step 1: Know Your “Settings Folder”

All of Hermes’s configuration lives in one place: a hidden folder called ~/.hermes/ on your computer. The ~ just means “my home folder.” Inside, you’ll find a few important files:

~/.hermes/
├── config.yaml     # Main settings (model, terminal, voice, etc.)
├── .env            # API keys and secrets (like passwords)
├── auth.json       # OAuth login info for providers
├── SOUL.md         # Your agent's personality/identity
├── memories/       # What your agent remembers
├── skills/         # Custom skills your agent created
├── cron/           # Scheduled jobs
├── sessions/       # Active gateway sessions
└── logs/           # Error and activity logs (secrets are auto-hidden)

Don’t worry about memorizing this. Just know that config.yaml is the main control panel, and .env is where your secret keys live.

Step 2: The Easiest Setup (No Manual Editing!)

If you’re new, don’t hand-edit config.yaml. Instead, run this one command:

hermes setup --portal

This does three amazing things for you:

One OAuth login (just click “Sign in with Google” or similar) gets you a model provider.
It automatically sets up all four Tool Gateway tools (like web search, file access, etc.) — no manual configuration.
If you’re a Portal subscriber, you get 10% off token-billed providers.

It’s like ordering a fully-furnished apartment instead of buying empty rooms and assembling furniture yourself.

Step 3: Viewing and Changing Settings

Once you’re up and running, you’ll want to tweak things. Here are the commands you’ll use daily:

hermes config              # See your current configuration
hermes config edit         # Open config.yaml in your text editor
hermes config get KEY      # Check one specific value (e.g., "model")
hermes config set KEY VAL  # Change a value (e.g., "model gpt-4o")
hermes config unset KEY    # Remove a user-set value (back to default)

Pro tip: Use hermes config get and hermes config set instead of editing the file manually. It’s safer — Hermes validates your input and prevents typos.

Step 4: After Updates — Check and Migrate

When you update Hermes, new settings might be added. Don’t panic — two commands help:

hermes config check        # Tells you which options are missing
hermes config migrate      # Walks you through adding missing options interactively

Think of config check as a health check that says “you’re missing vitamin C,” and config migrate as the guided wizard that hands you the supplement and a glass of water.

Step 5: What’s in `config.yaml` Anyway?

Common things you’ll set here:

Model — which AI model to use (e.g., GPT-4, Claude, Llama)
Terminal — how your agent interacts with your terminal
TTS — text-to-speech voice settings (if you want it to talk)
Compression — how to compress long conversations to save tokens

You don’t need to know all of these now. Just remember: if you want to change something, look for its key in config.yaml or use hermes config set.

Step 6: Keep Secrets Secret

Your .env file holds API keys and secrets. Never share this file or paste its contents in a chat. Hermes automatically redacts secrets from logs, but you should still treat .env like your house keys — keep it private.

Summary

All settings live in ~/.hermes/, with config.yaml as the main file.
For beginners, hermes setup --portal is the fastest path — no manual YAML editing needed.
Use hermes config get/set to safely read and change individual settings.
After updates, run hermes config check and hermes config migrate to stay current.
Keep .env and auth.json private.

Next up: Tutorial 8 — “Your Agent’s Personality: SOUL.md” — where we’ll give your Hermes agent a unique character and voice. See you there!