People searching for Hermes Agent Docker install usually need one of two things: run the whole agent as a long-lived container, or keep the CLI local while sandboxing terminal commands in Docker. This page is the Docker/self-hosted path. If you just want the fastest first run, start with install Hermes Agent; if you need to verify the source first, open the Hermes Agent GitHub repository guide. If Docker is already failing, jump to Hermes Agent troubleshooting.
Quick answer#
For a reliable Hermes Agent Docker install, prove the CLI works first, put provider keys in .env or config.yaml, mount ~/.hermes so memory and skills survive restarts, then run one visible smoke test before adding Telegram, Discord, cron jobs, or VPS hardening. Use FlyHermes if you want the hosted path without maintaining Docker, gateway processes, and provider credentials yourself.
Choose Docker only after the CLI works#
Before treating Docker as the default production path, ask whether you actually want to own container operations. Docker is strong for reproducible self-hosting, but it also adds volume ownership, environment propagation, network exposure, image updates, and dashboard/gateway restart checks. If your goal is simply a browser/mobile Hermes workspace with connected channels, read the self-hosted vs hosted AI agent comparison and the FlyHermes pricing page before expanding the container stack.
A helpful Hermes Agent Docker install starts outside Docker. First prove the normal CLI can run hermes doctor and one hermes chat -q "reply ok" turn. Then move the same working profile into Docker with mounted state, provider keys, and logs you can inspect. This prevents the most common failure mode: debugging install, provider auth, mounted volumes, gateway routing, and container networking at the same time.
Use Docker when you need repeatable deployment, VPS uptime, isolated terminal execution, or a containerized gateway service. Avoid Docker for the first five minutes if the only goal is to understand Hermes. If the real goal is browser/mobile access with Telegram or Discord uptime and no server maintenance, compare FlyHermes before owning the Docker stack.
Hermes Docker quick checks#
Searchers landing here for Hermes Docker or Hermes Agent Docker usually need a working container, not a theory page. Use this order:
- Prove
hermesanswers locally with the provider you intend to use. - Mount the Hermes home directory so config,
.env, sessions, memory, and skills survive restarts. - Start Docker Compose with one visible CLI or gateway smoke test.
- Check
hermes gateway statusbefore adding Discord, Telegram, Slack, cron, or webhook workflows. - Move to VPS hardening only after logs show the same profile and provider inside the container.
If the Docker path is only there to keep an assistant online for messaging, compare it with FlyHermes before spending time on restart policies, backups, gateway tokens, and provider billing.
Choose the right Docker path#
- Docker Compose for the whole agent: best when Hermes should stay online on a VPS, receive gateway messages, and survive restarts.
- Docker terminal backend: best when the Hermes CLI runs on your laptop but shell commands should execute in isolated containers. Use the Docker terminal backend guide for that path.
- Plain local install first: best for first-time setup, provider login, and debugging. Follow the install guide, then containerize after the first answer works.
Do not mix those paths while debugging. A bad API key, missing volume, or disabled gateway can all look like “Docker is broken” if you add everything at once.
If you are choosing between Docker and managed hosting, use Docker when you need infrastructure control, local volumes, and custom gateway wiring. Use FlyHermes when the goal is simply to keep Hermes online without maintaining containers, restart policies, secrets, backups, and provider routing yourself.
Docker Compose checklist#
- Install and test Docker —
docker --versionanddocker compose versionshould both work before Hermes enters the picture. - Create the Hermes home volume — mount the host
~/.hermesdirectory or a named volume to the container's Hermes home soconfig.yaml,.env, sessions, memory, and skills persist. - Put secrets outside the image — provider API keys, Telegram tokens, Discord tokens, and webhook secrets belong in environment variables or mounted config files, never in a baked image.
- Start with one provider — configure Nous Portal, OpenRouter, Anthropic, OpenAI, or a local provider and run
hermes doctoror onehermes chat -qsmoke test. - Add gateways after the model works — only then run
hermes gateway setup,hermes gateway status, and a real Telegram or Discord test message. - Pin and document production settings — record the image/tag, mounted volumes, restart policy, exposed ports, and backup path for
~/.hermes.
Minimal smoke-test sequence#
Use this sequence after the container starts. It gives you one clean pass/fail point before you spend time on gateway permissions, compose restart policies, or provider dashboards:
hermes --version
hermes config path
hermes config env-path
hermes doctor
hermes chat -q "Reply with the active provider name and one sentence."
If the smoke test cannot see the config path you expected, fix the volume mount before touching model settings. If it sees config but the model fails, switch to the provider/key checklist in Hermes troubleshooting.
Common Docker failures#
hermes works locally but not in the container#
The container probably does not have the same Hermes home, PATH, or provider credentials as your shell. Print hermes config path and hermes config env-path inside the container, then compare those paths to the mounted volume.
Memory, skills, or sessions disappear after restart#
The Hermes home directory is ephemeral. Mount ~/.hermes or a named volume and back it up. This is especially important if you rely on persistent memory or reusable Hermes skills.
Telegram or Discord connects once, then stops replying#
Check the gateway process, not just the container status. Run hermes gateway status, inspect gateway logs, and verify the platform token. For platform-specific setup, use the Telegram integration or Discord integration pages.
Docker terminal backend fails with exit 127#
That is usually not a Compose problem. It means Hermes is configured to run terminal tools in Docker but Docker is unavailable from the current process. Either repair Docker or temporarily switch the terminal backend to local with hermes setup terminal.
When Docker is the wrong answer#
Docker is powerful when you want isolation and a persistent VPS, but it adds operational surface area: image updates, volume ownership, network rules, restart policies, and gateway logs. If your goal is “I want Hermes available from chat without maintaining a server,” use the managed FlyHermes path. If your goal is “I want full control on my own machine,” continue with self-hosting, VPS hosting, and security hardening.
Before committing to Docker long term, read the self-hosted AI agent guide: it separates real control from VPS, gateway, provider-key, backup, and update maintenance. If that operational work is not worth it, use FlyHermes instead.
Docker drift after updates#
Recent support threads such as Custom docker_image not being read and YouTube Content Tool docker show that Docker can make an update look broken even when Hermes itself updated correctly. If tools fail after an update, check the terminal backend in Terminal Backends Explained, then use the Hermes update command hangs smoke test before rebuilding containers.
Provider reliability is part of this workflow too. If setup fails because credits, API keys, rate limits, or model switching are unclear, use the Hermes Agent model provider costs guide to choose a primary model lane, a cheaper routine-work lane, and a local or hosted fallback before blaming the rest of the stack.
If Docker is part of a true always-on deployment, pair this with the Hermes 24/7 AI agent setup checklist so gateway supervision, provider credits, dashboard visibility, and FlyHermes fallback decisions are handled together.
June 2026 Docker fixes to know before debugging#
Before treating a Docker failure as a bad install, update Hermes and retry. Recent fixes run config migrations during container boot, reject unsupported arbitrary --user starts with clearer guidance, repair UID-remap/chown handling, and make Docker MCP command resolution work for bare npx, npm, and node commands. Those changes turn several old “container is broken” symptoms into normal update-and-restart fixes.
If the problem remains, use the Docker troubleshooting checklist and keep the mounted Hermes home intact while you inspect ownership, env vars, provider setup, gateway logs, and dashboard access.