Docker & Compose

By the end of this page the daemon runs as a container with durable state and a pinned version — the way to run the server on Windows hosts and on platforms without a native binary.

Run it

docker run -d -p 8137:8137 -v oh-data:/data ghcr.io/openheaders/ohd:latest

State lives in the /data volume; the daemon listens on 0.0.0.0:8137 inside the container, and Docker’s port mapping decides what reaches it. Publish -p 127.0.0.1:8137:8137 to keep it host-local, or -p 8137:8137 to expose it on the host’s interfaces. Pin a version tag for reproducible deployments — tags match the daemon’s released versions:

docker run -d -p 8137:8137 -v oh-data:/data ghcr.io/openheaders/ohd:2026.10.0

Compose

services:
  ohd:
    image: ghcr.io/openheaders/ohd:2026.10.0
    restart: unless-stopped
    ports:
      - "8137:8137"
    volumes:
      - oh-data:/data

volumes:
  oh-data:

Claim it

A fresh container has no administrator — the first browser to reach it creates one (First run). The container’s bind is never loopback from the host’s point of view, so the browser presents the setup code the daemon prints at boot:

docker logs <container> | grep -A2 'unclaimed'

And because the claim happens in a browser, the URL must be a secure origin: put a TLS reverse proxy in front and claim at https://<your-host>/, or forward loopback from the container’s host over SSH (ssh -L 8137:127.0.0.1:8137 you@dockerhost) and claim at http://127.0.0.1:8137/ — which the daemon still sees as a bridge peer, so bring the code either way. Each restart mints a new code, so read it from the log of the run you are claiming.

Operating a containerized daemon

Machine bootstrap token: ohd show-token needs the daemon stopped and the same data dir. Stop the container, then run it against the volume — and note the claim revokes unbound tokens, so mint this after claiming, not before:
docker stop <container> docker run --rm -v oh-data:/data ghcr.io/openheaders/ohd:2026.10.0 show-token --data-dir /data docker start <container>

Settings work the same way (stopped daemon, same volume):

docker run --rm -v oh-data:/data ghcr.io/openheaders/ohd:2026.10.0 config set mcp.enabled true --data-dir /data

TLS: the container answers cleartext on its bind; put a TLS-terminating reverse proxy in front for anything beyond a trusted network, exactly as on a native install — see LAN vs TLS proxy.
Upgrade: pull the newer tag and recreate the container; state rides the volume. ohd upgrade is for native binaries only.

Backup: stop the container and snapshot with the same tooling — see Backup & restore:

docker run --rm -v oh-data:/data -v "$PWD/backups:/backups" \
  ghcr.io/openheaders/ohd:2026.10.0 backup /backups/oh-2026-08-22 --data-dir /data

Server

Run it

Operate it

Run it

Compose

Claim it

Operating a containerized daemon

​Run it

​Compose

​Claim it

​Operating a containerized daemon

Run it

Compose

Claim it

Operating a containerized daemon