Understand the Hermes Docker Entrypoint Dispatcher
Hermes uses an entrypoint dispatcher so one container image can run correctly in ordinary Docker and on platforms that insert their own init process. The important boundary is who owns PID 1. That decision affects supervision features, not whether the requested Hermes command can run.
Follow the two startup paths
When the Hermes entrypoint is PID 1, entrypoint-dispatch.sh hands control to s6-overlay at /init. The full supervision tree can then start and monitor services such as dashboards and profile gateways.
When a platform wraps the image with another PID-1 process—for example docker run --init or some Fly.io, Nomad, and Kubernetes configurations—the dispatcher runs the stage-two bootstrap directly. The requested command still runs, but s6-supervised dashboards and per-profile gateways are not available on that fallback path.
Argument routing is deliberate: no arguments launch hermes; an executable command runs directly; other arguments are interpreted as hermes <arguments>.
Deployment checklist
- Confirm which process owns PID 1 in the target runtime.
- Decide whether the workload needs the full supervision tree.
- Test the exact command and argument shape used by the platform.
- Mount persistent Hermes state explicitly.
- Verify gateway and dashboard processes rather than assuming they started.
- Capture startup logs for the selected path.
Common pitfalls
- Treating every container runtime as plain Docker. Platform init wrappers can change the startup branch.
- Assuming command success proves supervision. A direct command may work while s6-managed services are absent.
- Forcing two init systems to compete. Understand the platform wrapper before overriding the entrypoint.
- Ignoring persistent state. A correct entrypoint does not preserve profiles or sessions unless storage is mounted.
Verification
Inspect the live process tree and startup logs. Confirm whether /init or the stage-two bootstrap launched, then test the exact required service: CLI command, gateway, dashboard, or profile worker. Restart the container once to verify persistent state and repeatable startup.
Official reference: Run Hermes Agent with Docker.