Hermes Agent Docker Troubleshooting

Hermes Agent runs well in Docker, but Docker failures often look scarier than they are because the real problem is usually ownership, mounted state, provider config, or gateway reachability. Start with the container boundary before you rewrite Hermes config, then compare the broader install and update troubleshooting guide if the same failure also appears outside Docker.

The common Docker failure pattern#

Recent self-hosting discussions keep surfacing the same buyer objection: the agent is valuable, but the container work is not the job. If debugging UID remaps, mounted state, missing .env values, gateway ports, or dashboard exposure becomes the main task, use the self-hosted vs hosted AI agent guide to decide whether FlyHermes is a better fit for this workflow.

Most Docker support threads fall into one of these buckets:

• The container cannot write to the mounted Hermes home.
• A config file was created by an older Hermes version and did not migrate during boot.
• Provider or MCP credentials exist on the host but not inside the container.
• The gateway is running, but the network, topic, token, or allowed-channel config is wrong.
• The dashboard is reachable on the wrong interface or exposed more widely than intended.

That is why Docker debugging should start with the runtime boundary, not with a reinstall.

Step 1: preserve state before touching the container#

Your Hermes home contains config, memory, skills, sessions, cron jobs, and gateway state. Back it up before destructive experiments:

cp -a ~/.hermes ~/.hermes.backup.$(date +%Y%m%d-%H%M%S)

Then check whether the same path is mounted into the container. A rebuilt image is normal. A missing or replaced Hermes home is not.

Step 2: update before debugging old container bugs#

The v0.15.2 patch wave and June 2026 mainline fixes matter for Docker. Recent changes added container boot config migrations, clearer rejection of unsupported arbitrary --user starts, better UID-remap ownership handling, and safer Docker command resolution for MCP servers that call npx, npm, or node.

Use the latest image or checkout, then run:

hermes doctor
hermes tools

inside the container. If hermes doctor cannot see your provider config, fix the mounted env/config first.

Step 3: fix UID and ownership issues directly#

If the container cannot write to ~/.hermes, inspect ownership instead of rotating tokens:

id
ls -la ~/.hermes

Avoid forcing docker run --user <random-uid> unless the image explicitly supports that path. The recent Hermes Docker fixes now fail unsupported arbitrary UID starts with clearer guidance because a random user can leave build trees, caches, or the Hermes home unwritable.

Step 4: verify provider and MCP credentials inside Docker#

A host shell may have ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, or MCP header secrets while the container does not. Confirm the container can see what Hermes needs without printing secret values:

python - <<'PY'
import os
for key in ['ANTHROPIC_API_KEY','OPENAI_API_KEY','XAI_API_KEY']:
    print(key, 'set' if os.getenv(key) else 'missing')
PY

For MCP servers, prefer environment placeholders in config only when the container actually receives those environment variables. Recent Hermes discovery probes expand ${ENV} in header auth, so update before assuming the MCP server itself is broken.

Step 5: separate dashboard access from gateway uptime#

The Hermes Web UI is an operations dashboard. The gateway is what answers Telegram, Discord, Slack, webhooks, or other channels. Debug them separately:

• Dashboard problem: check bind host, port, reverse proxy, and auth mode.
• Gateway problem: check token, allowed channel, topic/thread routing, webhook reachability, and process logs.
• Provider problem: check model/provider credentials and rate-limit errors.

Do not expose the dashboard publicly just to make it convenient. Use localhost, VPN, SSH tunnel, or a trusted reverse proxy.

When Docker is the wrong answer#

Self-hosting gives control, but it also gives you uptime work: image updates, config migrations, mounted volumes, provider secrets, gateway restarts, and dashboard security. If the job is “give me a phone-accessible agent that keeps running,” compare self-hosted versus hosted AI agents and the 24/7 Hermes setup guide before turning one Docker error into a weekend ops project.

Docker failures that look like gateway or model failures#

A container problem often surfaces as a Telegram, Discord, MCP, or provider symptom. Before changing prompts or model routes, prove the container boundary:

• hermes config path and hermes config env-path inside the container point at the mounted Hermes home you expect.
• hermes doctor can see the provider credentials without printing secrets.
• File ownership lets Hermes write sessions, memory, logs, skills, and cron output.
• Gateway logs are coming from the running container, not from a stale host process.
• The dashboard/Web UI is bound only where you intend, with auth for any non-local exposure.

If the Docker checks are green but messaging still fails, move to the gateway troubleshooting guide. If Docker itself is the recurring tax, compare the hosted FlyHermes path.

Docker note: Obsidian vaults need mounted paths#

If Hermes can edit an Obsidian vault from the local CLI but not from Docker, the container probably cannot see the desktop folder. Mount the scoped vault folder explicitly and avoid mounting your entire home directory. For the safer workflow, see the Hermes Agent Obsidian integration guide and the Docker Compose setup page.