Docker
Run a Hub in the Hubzoid container image with Docker Compose, with sign-in on and its data kept in a mounted Hub folder.
At the end of this guide a Hub runs in a container with sign-in on, its data lives in a Hub folder on the host, and you are signed in as its first administrator. The image runs hubzoid run /hub against the folder you mount, so it behaves like a native install: the same processes, the same .env and the same public port.
Use the image when pip install hubzoid is impractical on the host, when you want the reviewed dependency set, or when your platform runs containers. For the processes and data stores a container runs, see deployment topologies.
What you need
- Docker with Compose, and a clone of the Hubzoid repository (opens in a new tab) checked out at the release you want (
git checkout v<version>), for theDockerfileand thedocker/Compose files. - A model provider key, such as OpenRouter, Anthropic or OpenAI. A container cannot use the
claudeorcodexlogin on your laptop.
Run a Hub in a container
Build or pull the image
Build the image from the checkout. It installs the reviewed dependency set in requirements.lock, so the image is the release you checked out:
docker build -t hubzoid:local .Or use the published image. Each release is pushed to the GitHub Container Registry for amd64 and arm64, after the release checks pass:
docker pull ghcr.io/hubzoid/hubzoid:<version>Releases are tagged with the version number without the leading v, and with latest. Pin the version tag in production so a restart never changes the release you run.
Make a Hub folder
The Compose file mounts one Hub folder at /hub. If you already have a Hub, use its folder. Otherwise make the starter with the image itself, with no Python needed on the host:
mkdir -p ~/my-hub && chmod a+rwX ~/my-hub
docker run --rm -v ~/my-hub:/hub hubzoid:local init /hubThe chmod matters on Linux, because the container runs as its own unprivileged user. You can also clone a ready-to-use Hub instead.
Turn sign-in on in the Hub's .env
The published port is reachable from other machines, so the Compose file turns sign-in on. Before the first start, set a model the container can use and the first administrator in the Hub's .env:
MODEL=openrouter/anthropic/claude-haiku-4.5
OPENROUTER_API_KEY=sk-or-...
HUBZOID_ADMIN_EMAIL=sam@example.com
HUBZOID_ADMIN_PASSWORD=<at least 8 characters>
HUBZOID_PUBLIC_URL=https://kestrel.example.comHUBZOID_PUBLIC_URL is the address people open. It is needed behind a proxy and for Google, Microsoft or OpenID Connect sign-in. Values in the Hub's .env win over the Compose defaults.
Start it with Compose
From the repository checkout, name the Hub folder with HUB_PATH, an absolute path:
HUB_PATH=$HOME/my-hub docker compose -f docker/docker-compose.yml up -dFollow the container's log until the ready line says sign-in is on:
docker compose -f docker/docker-compose.yml logs -f hubzoid✓ Hubzoid is ready: https://kestrel.example.com (sign-in on)Sign in and check
Put a reverse proxy with TLS in front of port 3080, exactly as on a single server. Open the address and sign in with the administrator from .env. Administrators must set up two-step sign-in by default, so scan the QR code, enter a code and save the ten recovery codes. Then remove HUBZOID_ADMIN_EMAIL and HUBZOID_ADMIN_PASSWORD from .env.
Run the doctor inside the container:
docker compose -f docker/docker-compose.yml exec hubzoid hubzoid doctor /hubFix every check marked ✗.
PostgreSQL and the shared browser
The docker/ (opens in a new tab) folder has two more Compose files that add to the base file.
docker/docker-compose.postgres.yml adds a postgres:17 service named db, whose port is not published, and sets the Hub's DATABASE_URL to postgresql+psycopg://hubzoid:${POSTGRES_PASSWORD}@db:5432/hubzoid. The Hub waits for the database health check. Use letters and digits for the password, because it goes into a URL.
HUB_PATH=$HOME/my-hub POSTGRES_PASSWORD=<letters and digits> \
docker compose -f docker/docker-compose.yml -f docker/docker-compose.postgres.yml up -dHubzoid's tables and the workflow engine's dbos schema go into the one hubzoid database, stored in the hubzoid-pg volume. Uploads and runtime files stay in the mounted Hub folder. This single DATABASE_URL layout suits one Hub. Deployment topologies explains why.
The image
The image runs hubzoid run /hub as an unprivileged user and publishes one port.
Every property of the image
| Property | Value |
|---|---|
| Base | python:3.12-slim-trixie (Debian 13, whose SQLite is new enough for the workflow engine) |
| System packages | postgresql-client, for hubzoid backup of PostgreSQL databases |
| Python dependencies | requirements.lock, including the PostgreSQL driver |
| User | hubzoid, unprivileged |
| Working directory | /hub |
| Entrypoint and default command | hubzoid, then run /hub |
| Defaults | PORT=3080, BRIDGE_PORT=8000, HUBZOID_HOST=0.0.0.0 |
| Health check | GET /healthz on PORT every 30 seconds |
| Published port | 3080, the edge |
Publish only port 3080. The edge there serves the web app, download links, Settings at /settings and the hosted MCP server. The bridge listens on 127.0.0.1 inside the container.
Arguments after the image name replace the default command, for example hubzoid:local run /hub --port 3080. Channels such as Slack turn on with a file in the Hub's channels/ folder, so the default command starts them too. Without Compose, the same Hub runs with docker run -d --restart unless-stopped -p 3080:3080 -v "$HOME/my-hub:/hub" hubzoid:local.
Compose variables and their defaults
| Compose variable | Default | What it sets |
|---|---|---|
HUB_PATH | none, required | The Hub folder mounted at /hub |
HUBZOID_IMAGE | hubzoid:local | The image. Set ghcr.io/hubzoid/hubzoid:<version> to run a published one. |
HUBZOID_PUBLISH | 3080 | The host port, or 127.0.0.1:3080 for this machine only |
HUBZOID_AUTH | true | Sign-in |
Where data lives
Everything a Hub writes stays in the folder mounted at /hub, so it survives container replacement and hubzoid backup covers it.
| Path in the Hub folder | Contents |
|---|---|
.hubzoid/ | The SQLite databases (accounts, sessions, conversations, grants, usage and workflow state), the workflow engine's dbos.db, chat files under chats/, the download-link signing key, the deployment key secret.key and scheduled backups under backups/ |
.inbound/ | Inbound channel state, including stored webhook events |
logs/ | Hub runtime logs |
output/ | Files the agent made for people |
With the PostgreSQL file, the database lives in the named volume hubzoid-pg, and hubzoid backup dumps it into the archive. Keep a copy of the deployment key apart from the data, because backups leave it out. See backup and restore.
Operator commands
Run operator commands inside the container against /hub:
docker compose -f docker/docker-compose.yml exec hubzoid hubzoid backup /hub --out /hub/backup.tar.gz
docker compose -f docker/docker-compose.yml exec hubzoid hubzoid admin create priya@example.com /hub
docker compose -f docker/docker-compose.yml exec hubzoid hubzoid schedule status /hubFor liveness probes, the public port answers GET /healthz. GET /healthz/workflows reports workflow health for an uptime monitor. See observability.
To upgrade, back up, stop the container, pull or build the new image and start again. The new version upgrades its tables at its first start. See upgrading.
Container platforms
The image is the entry point for ECS, Kubernetes and other orchestrators. The wiring is yours. Two rules keep a Hub's data safe:
- One task or pod per Hub. Give each Hub its own service with a desired count of 1 and no horizontal autoscaling. Two copies of one Hub would compete for its workflow engine and SQLite files. Use PostgreSQL when processes run on more than one machine, and rehearse workflow recovery and upgrades.
- No SQLite on a network filesystem. Keep the
.hubzoiddatabases on block storage such as an EBS volume, not on EFS or another network filesystem, or move Hubzoid's stores to PostgreSQL.
The container listens on PORT (default 3080) and accepts .env values as container environment variables. A value in the Hub's own .env still wins, so leave a setting out of that file to drive it from the platform.
What differs in a container
| Feature | In the image |
|---|---|
MODEL=claude-local | Does not work, because the image has no claude CLI. Use a model provider key. |
MODEL=codex-local | Does not work in the base image. Build your own image with a supported Codex CLI and private, persistent login storage for the service account. Do not mount an operator's whole home folder. |
| Shared browser in direct mode | The image has no Node.js, so Hubzoid cannot start the browser itself. Use docker/browser-compose.yml. |
| Mounted Hub folder | Must be writable by the container's user. On Linux, chown -R 999:999 my-hub, or run with --user "$(id -u):$(id -g)". |
If something goes wrong
| What you see | What to do |
|---|---|
Set HUB_PATH to your hub folder, an absolute path | Compose needs HUB_PATH. Make a Hub folder as in step 2 and pass its absolute path. |
The container stops with Sign-in is off, so listening on 0.0.0.0 | HUBZOID_AUTH is false in the Hub's .env. Set it to true with a first administrator, or follow the without sign-in tab. |
| Nobody can sign in | No account exists yet. Set HUBZOID_ADMIN_EMAIL and HUBZOID_ADMIN_PASSWORD, or run hubzoid admin create <email> /hub --owner inside the container. |
The container cannot write to /hub | The mounted folder is not writable by the container's user. Fix its ownership as in the table above. |
The agent cannot answer with MODEL=claude-local or codex-local | The image has neither CLI. Choose a provider and its key in .env. |