Throwing Hermes into the Swamp

Five days in, Hermes is already running things I've been meaning to automate for months: daily AI briefs, overnight wifi roaming diagnostics, price watching, a sermon notes processor, rough blog drafts. All local — Qwen model on my M5 Max, nothing leaving the machine.

I passed on OpenClaw when it launched. The idea was right — always-on, extensible, tool use — but the reports were bad. Exploits in the skill store, inference costs in the hundreds per week. Hermes feels like the same premise with the obvious problems fixed.

The setup is mostly frictionless once the boring parts are right: the runtime user, the skill paths, and the environment snapshot every tool subprocess actually runs with.

The Part That Actually Matters

Hermes initializes a session by running a login shell with HOME=/opt/data/home. That shell captures its environment with export -p into a file like this:

/tmp/hermes-snap-{id}.sh

Every tool command sources that snapshot before it runs.

So if SWAMP_API_KEY is missing or stale in the snapshot, it does not matter that the .env files are correct. The subprocess has already been handed the wrong value. You can fix /opt/data/.env and /opt/data/.hermes/.env all day and still watch tool calls fail, because the snapshot wins.

That was the thing I missed.

The Persistent Fix

The critical file was:

/opt/data/home/.bash_profile

It needs to contain:

export SWAMP_API_KEY=<key>

Because Hermes creates the snapshot from a login shell, .bash_profile is the place that gets read early enough for the captured environment to be right. Once that file had the key, the next recreated session picked it up and Swamp worked from inside tool subprocesses.

There are four places I need to keep in sync now:

/opt/data/.env
/opt/data/.hermes/.env
/home/mat/docker-configs/services/hermes/.env
/opt/data/home/.bash_profile

The first three are the obvious Docker/Hermes config locations. The fourth one is the one that actually made the tools work.

For future rotations, I do not want to remember any of that by hand:

swamp model method run hermes-env rotateSwampKey --arg newKey=<new_key>

That updates all four places and recreates the container. This is exactly the kind of tiny operational ritual that should become a Swamp method instead of living in my head.

And hopefully this means Swamp is actually persistently installed in Hermes now. I have thought that before. This time I at least know which layer to check when it disappears.

The Install Thrash

Getting there took longer than it should have.

I ran the Swamp install as root first. Then as my user. Then as hermes. The Docker container runs under a hermes user, and that's the one that matters — that's the user the gateway runs as, that's where files get written, that's who can actually execute models.

Swamp's Rust binary goes to /usr/local/bin/swamp. If you're running Debian 13, it should work out of the box. But the install path had almost nothing to do with the final failure.

It was still worth cleaning up, because mismatched runtime users create weird permission problems. It just was not the bug.

What the Agents Did While I Was Busy

This is the part I want you to skip if you know where you're going. While I was thrashing between accounts, the agents — reading instructions from AGENTS.md and skimming config files — started making decisions on their own.

They created symlinks across directories. They tried to build a repo called agentic-ops that doesn't exist. They put skill copies in three locations at once.

The root cause there was different: agents can't find skills they weren't given explicit permission to load. They see a skill reference, can't find it, and start building workarounds. Symlinks first. Phantom repos second.

That problem was fixed with the external skills config:

skills:
  external_dirs:
    - /opt/data/swamp-hub/.agents/skills
    - /opt/data/skills/homelab

This tells Hermes where to look for skills beyond the built-in ones. Without it, agents can't load the swamp-model or swamp-workflow SKILL.md files, and they start improvising instead of asking.

So there were really two fixes, but only one of them was the auth fix:

1. Put SWAMP_API_KEY in /opt/data/home/.bash_profile so the Hermes session snapshot captures it.
2. Add the Swamp skill directories to ~/.hermes/config.yaml so agents stop inventing structure.

The Prompt

If you're setting this up from scratch, I would not use my first prompt anymore. It pointed at the right neighborhood, but it missed the session snapshot issue.

Use this instead:

curl -fsSL swamp-club.com/install.sh | sh

What's Actually in Swamp-hub

The swamp-hub repo (/opt/data/swamp-hub) is separate from the core install. It holds my Swamp models, workflows, and extensions — the things I built over time as I asked for automations and started recognizing patterns worth repeating.

Inside it:

• The 11 swamp CLI skills (swamp-model, swamp-extension, swamp-issue, etc.)
• The offline meeting transcriber workflow — transcribes, diarizes, and summarizes meetings locally using mlx-whisper, pyannote, and Ollama. Three published models: @mgreten/mlx-whisper, @mgreten/pyannote-diarizer, @mgreten/meeting-summarizer.
• A hermes-review-kit extension — a daily cron job model that reviews what was done during the day, evaluates whether anything is worth turning into a published model or workflow, flags publishable candidates
• A cron-builder model for scheduling cron jobs, because Hermes churned on this
• Vault configs and workflow definitions

This is "post-setup" content. You don't need it to get running. But it's where the system actually gets useful.

A Word of Caution

If you're walking into this for the first time: don't let the agents auto-decide directory structure, skill locations, repo names, or auth wiring without running them by you first. Those decisions need a human with the full picture.

The agents saw a missing file and built a symlink. They saw a missing directory and created a repo. I saw a bad Swamp auth error and spent too long looking at install ownership instead of the captured shell environment.

The answer isn't to fight the agents. It's to give them the right config first, then let them work within it. That's a lesson I've learned many times in my day job, but because I was just vibe setting up this stuff, it bit me.

This was not my day job. This was something I was doing while being interrupted by my four kids, hanging out with my parents who were in from out of town, and running around.

So I let the agents take the wheel too early. And it didn't work out as best it could. Part of that might have been running local inference inside Hermes. Part of it was me not slowing down enough to read how the session environment was created.

Hopefully this heads some of it off at the pass for others.

The system works. You can ask it for things in plain English, have it build automations, and get results. It's worth the setup — but only if you get the boring basics right upfront: runtime user, skill paths, and the environment snapshot that every tool command actually runs with.