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 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.