My self-hosted Hermes on a VPS or Docker won't start. What should I check?
First find the last thing that actually worked: the installer, the hermes command, the gateway process, the web listener, or a model reply. A running Docker container does not prove that the Webapp is enabled; a page that opens does not prove that the configured model can answer. Read the error at that boundary before reinstalling or opening more ports.
This checklist follows Hermes v0.23.1, commit 3b42157, checked on 13 November 2026. It describes upstream source and documentation. We did not reproduce these failures or remedies on a VPS, run a model call, or qualify a new Vavio setup path for this article. Use the commands on the self-hosted machine you control; replace hermes in Docker examples with your actual container name.
Start with the symptom
| What you see | First check | What it distinguishes |
|---|---|---|
| The install stops before finishing | The first error in the install output and logs/install.log under the Hermes data directory |
Download, prerequisite or build failure |
hermes: command not found |
command -v hermes as the intended service user; inspect that user’s launcher directory and PATH |
A missing launcher versus a shell that cannot find it |
| The container exits or keeps restarting | docker ps -a and docker logs --tail 100 hermes |
A startup error versus a container that remains running |
| Hermes opens, but no model responds | hermes model, then hermes doctor from the same install/user/profile |
Provider configuration, credentials or connectivity |
| Browser connection refused, or proxy 502 | Gateway status, which web interface is enabled, its bind address and port | A missing listener versus a network/proxy problem |
| Permission denied or settings disappear | The /opt/data mount, its owner and the runtime UID/GID |
Wrong storage location or inaccessible persistent data |
hermes doctor includes provider-connectivity checks even without --live; it is not an offline-only command. --live adds real tool-backend probes, and --fix attempts changes. Start without those flags and read the findings before applying a repair. In a running official container, invoke the installed wrapper with docker exec -it hermes hermes doctor.
1. Did installation finish for the right user?
On a source install, use the official installer and its managed launcher. In this release, first-party installations use managed Python 3.14 and pinned tools. The broader Python range in pyproject.toml is not a promise that a fresh install runs on every older interpreter. Installing an arbitrary system Python or Node version is not the same as repairing the managed runtime.
The POSIX installer requires Git, curl, tar and SHA-256 utilities; source builds can also need a native compiler and platform libraries. Minimal Linux images can lack libatomic.so.1, required by the managed Node binary. The installer names the package-manager command when it cannot install that dependency. Record that exact error and have the administrator supply the named package rather than repeatedly rerunning setup under a different account.
For a non-root service, the official guide says to install as the intended service user: its home, tools, configuration and launcher must belong to that user. Check PATH from that account, not only from your administrator shell. The usual POSIX launcher directory is ~/.local/bin; reload the appropriate shell configuration after installation. Follow the current installation guide for your platform rather than hardcoding an internal virtual-environment path.
2. Is the container running the service you intended?
An interactive Hermes session and a persistent gateway are different launches. The official Docker guide first runs setup interactively with the data mount, then uses gateway run for a background gateway. Starting an interactive session without a usable terminal can exit; it does not automatically become a web server.
Read the actual container command and recent logs. Preserve the official image’s default entrypoint. When the image owns PID 1, it starts s6 and performs initialization, ownership setup and profile reconciliation. With docker run --init or a platform that supplies its own PID-1 wrapper, the dispatcher instead performs direct bootstrap and warns that supervised services are unavailable. Check for that warning if the expected dashboard or profile services never start. Replacing the entrypoint with a direct Python command can skip initialization. Even on the supervised path, a container that remains up still needs its gateway status and logs checked:
docker ps -a
docker logs --tail 100 hermes
docker exec hermes hermes gateway status
Gateway logs also persist on the mounted volume under logs/gateways/<profile>/current; interactive containers may route service console output differently from headless containers. Use the official log map when docker logs does not contain the error you need.
A public setup report from 7 November describes a Coolify/VPS deployment with no listener on port 9119 and an interactive session shutting down. That report is now closed. It illustrates the symptoms, not a diagnosis we reproduced or proof that today’s version has the same fault.
3. Are you opening the right web interface?
Hermes has separate listeners. Do not treat these ports as interchangeable:
| Interface | Default port | What must be configured |
|---|---|---|
| Gateway OpenAI-compatible API | 8642 | API_SERVER_ENABLED=true and a strong, usable API_SERVER_KEY even on loopback; a non-loopback bind also needs the appropriate host/network configuration |
| Dashboard | 9119 | For the supervised Docker service, HERMES_DASHBOARD=1 |
| Webapp, the Desktop interface in a browser | 9120 | webapp.enabled: true in the mounted config.yaml, then a gateway restart |
Check hermes webapp --status inside the container for the Webapp specifically. Publishing a Docker port does not turn its listener on. In ordinary bridge networking, a listener bound to 127.0.0.1 inside the container is reachable only there; a published port or proxy in another container needs the listener on a reachable container interface. For the Webapp, the official Docker guide uses webapp.host: 0.0.0.0 plus authentication. Host networking has different port-publishing behavior, so inspect your actual network mode.
For remote access, keep authentication in place. The Dashboard and Webapp refuse a non-loopback listener without an authentication provider; HERMES_DASHBOARD_INSECURE=1 no longer bypasses that requirement. Basic username/password authentication is documented for a trusted network or VPN, not direct public-internet exposure. Use the upstream guide’s appropriate authenticated deployment or a local listener reached through an SSH tunnel.
If a reverse proxy reaches the page but sign-in fails, check the Webapp’s public_url, the identity provider’s callback URL and dashboard.trusted_proxies. Trust only the actual proxy address or a bounded dedicated network. A proxy 502, a callback mismatch and an authentication refusal are different errors; opening every port does not resolve them. Follow the Docker Webapp/proxy instructions for the exact configuration.
4. Is the same persistent home mounted and writable?
The official image stores user data at /opt/data. Confirm that the running service and the setup command mount the same host directory there. A fresh or incorrectly resolved mount can look like lost settings even though the old files still exist elsewhere. Check the mount source and destination locally; avoid posting an unfiltered container inspection, which can include credentials.
For permission errors, compare the host directory’s numeric owner with the configured HERMES_UID and HERMES_GID (or PUID and PGID). The default runtime user is UID 10000; the image can remap it to the host owner. Match the intended owner using the official instructions. Do not solve a credential-directory error by making the entire data tree world-readable, and do not delete the volume to “start clean” before preserving the data you need.
On a source install, likewise confirm HERMES_HOME and the service account. A missing or inaccessible symlink target can stop home initialization with a storage error naming the path. Fix the named target and permissions rather than assuming the model provider is responsible.
5. Does the model fail, or only the browser tool?
If the command or Webapp opens but the first model request fails, return to provider setup in the same user/profile. Check the selected provider, model, endpoint, authentication and the provider’s actual error. Use the supported setup prompt or credential store; never paste the key into a troubleshooting chat. Our credential guide explains those boundaries. A configured key can still lack credit or access to the requested model. If the error mentions context limits or ignored tools, use the separate model troubleshooting guide.
If ordinary text work succeeds but Chromium fails, examine browser-specific logs and resource limits. The upstream Docker guide calls out shared memory and documents --shm-size=1g; check the container’s memory limit and docker stats --no-stream hermes as well. These are documented checks, not a guarantee that adding memory fixes your failure. See RAM and disk sizing for the separate capacity decision.
Keep the evidence before changing the install
Record the version or image digest, install method, selected profile, last successful step, exact error and what one change you tried. Retest the same failed step after that change. A page loading is a successful listener test; a model reply and a completed tool task are further tests.
For a report you can inspect before sharing, upstream provides hermes debug share --local. Despite the command’s name, --local prints without uploading. Review it for credentials, private paths and conversation content before sending an excerpt. Updating is a separate change: preserve your data and follow safe updates and rollback, rather than using an unrecorded upgrade as the first diagnostic step.
If server upkeep is the part you want to stop doing, compare your own VPS with managed hosting. Vavio provides a managed Hermes computer for $14.99 per month, with model usage billed separately. Its MCP server and CLI let a supported assistant help configure and check Hermes. That is an alternative to tending the server; the source-based checks above are for your own install, not a claim that we reproduced or fixed your deployment. The current offer lists what is included.
Sources
- Hermes v0.23.1 installation guide and prerequisites, checked 13 November 2026
- Hermes v0.23.1 Docker guide (processes, volumes, web listeners and permissions), checked 13 November 2026
- Doctor checks and provider connectivity, checked 13 November 2026
- Webapp listener configuration and default port, checked 13 November 2026
- Docker dashboard service enable switch and port, checked 13 November 2026
- Public VPS and Docker setup report (7 November, closed; not our reproduction), checked 13 November 2026
- API server startup requires a strong key even on loopback, checked 13 November 2026
- Vavio hosting offer, checked 13 November 2026
Written by Vavio with AI assistance and checked against pinned official Hermes v0.23.1 source and documentation. These are documented diagnostic checks, not fixes reproduced on a VPS or customer computer.