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#

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.