Installation

You will install Hubzoid into a Python virtual environment, create a small Hub and check the whole setup with one command. It takes a few minutes.

One package holds everything hubzoid run needs: the Hubzoid web app and its Settings, the bridge, the agent runtimes (OpenAI Agents SDK, Claude Agent SDK and local Codex), LiteLLM model routing, the channel adapters, the workflow engine and the hosted MCP server. There is no separate UI or Node install.

What you needCopy Anchor Link

python3.12 -m venv .venv
source .venv/bin/activate

pip install hubzoid

hubzoid version

hubzoid init my-hub

hubzoid doctor my-hub

✓ AGENTS.md present (hub.agents_md)
✓ .env present (hub.env)
· 2 configured key(s): 2 from the hub (config.layers)
✓ Agent builds: 'my-hub' via ClaudeRuntime (runtime.build)
· hubzoid <version> (deps.versions)
✓ SQLite <version> (deps.sqlite)
· Not created yet; created at first start (db.operational)
· Not created yet; created at first start (db.hub)
✓ 1 bridge key(s) set (auth.bridge_keys)
· Sign-in is off: local mode, whoever opens the web app is the hub's owner (admin@localhost). Fine on this machine. (auth.chat_signin)
· Chat UI: Hubzoid web app (ui.mode)
✓ Local mode: the web app stays on 127.0.0.1 (exposure.local_mode)
· No deployment key yet; one is created in <path>/my-hub/.hubzoid/secret.key when first needed. Back it up apart from the data. (deployment.key)
✓ The public port listens on 127.0.0.1; bridges stay on 127.0.0.1 (exposure.bind)
· claude-local: uses the local `claude` login (check it with `claude /status`) (model.credentials)

You are ready for the quickstart. The rest of this page covers PostgreSQL, a source install and Docker.

Use PostgreSQLCopy Anchor Link

Hubzoid stores its data in SQLite inside the Hub folder by default. To use PostgreSQL instead, install the postgres extra, which adds the psycopg 3 driver:

pip install "hubzoid[postgres]"

Then point the Hub at the database with the postgresql+psycopg:// form of the URL. For several Hubs, set it once in the .env next to hubzoid.yaml:

DATABASE_URL=postgresql+psycopg://hubzoid:<password>@db.internal:5432/hubzoid

Hubzoid's own tables (accounts, conversations, access, usage and workflow state) and the workflow engine's dbos schema share that database, and each upgrades its own tables at start. Deployment topologies explains when to choose PostgreSQL.

Install from sourceCopy Anchor Link

Install from a clone when you want to read or change Hubzoid itself. A development branch can be ahead of the package on PyPI.

git clone https://github.com/hubzoid/hubzoid.git
cd hubzoid
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
hubzoid init my-hub
hubzoid run my-hub

The dev extra adds pytest and the packaging tools contributors use. pip install -e . installs without them. The web app and Settings are served from the built bundle in hubzoid/portal_dist. After you change anything in portal/, rebuild it with cd portal && npm ci && npm run build.

Run in DockerCopy Anchor Link

Build the image from a clone. The Dockerfile installs the checked-out source with the reviewed dependency set in requirements.lock, so the image version is the version you checked out. Each release is also published as ghcr.io/hubzoid/hubzoid:<version> for amd64 and arm64.

git clone https://github.com/hubzoid/hubzoid.git
cd hubzoid
docker build -t hubzoid .

The image listens on all interfaces, so it starts only with sign-in on. Before the first start, add these lines to the Hub's .env, and remove the two administrator lines after it:

HUBZOID_AUTH=true
HUBZOID_ADMIN_EMAIL=you@example.com
HUBZOID_ADMIN_PASSWORD=<a long password>
# HUBZOID_PUBLIC_URL=https://hub.example.com   # behind a proxy, or for Google sign-in

Then run it with the Hub folder mounted at /hub:

docker run -d --restart unless-stopped \
  -p 3080:3080 \
  -v "$PWD/my-hub:/hub" \
  hubzoid

No Hub yet and no Python on the host? The image can write the starter for you:

mkdir -p ~/my-hub && chmod a+rwX ~/my-hub
docker run --rm -v ~/my-hub:/hub hubzoid init /hub

The starter's .env says MODEL=claude-local, which the image cannot use, so change it to a provider model and its key.

Things to know about the image:

• Models. MODEL=claude-local and MODEL=codex-local do not work inside it, because it has no claude or Codex CLI. Set MODEL and a provider key in the Hub's .env.
• State. It stays in the mounted Hub folder (.hubzoid/), so it survives container restarts and hubzoid backup covers it.
• Ports. Publish only port 3080. It serves the web app, downloads, Settings and MCP. The bridge stays on 127.0.0.1 inside the container.
• Trying it without sign-in. Publish the port on this machine only with -p 127.0.0.1:3080:3080 and add -e HUBZOID_ALLOW_UNAUTHENTICATED_NETWORK=true. Anyone who can reach that port uses the Hub as its owner.
• Permissions on Linux. The container runs as an unprivileged user, so it must be able to write the mounted folder, for example chown -R 999:999 my-hub, or run with --user "$(id -u):$(id -g)".
• Commands. The image runs hubzoid run /hub on Python 3.12 (Debian 13, SQLite 3.46). Put other arguments after the image name to run a different command.

Docker ComposeCopy Anchor Link

docker/docker-compose.yml runs one Hub with SQLite and sign-in on. It needs HUB_PATH, the absolute path of your Hub folder. docker/docker-compose.postgres.yml adds a PostgreSQL 17 container whose port is not published.

# SQLite: state lives in the mounted Hub folder
HUB_PATH=$PWD/my-hub docker compose -f docker/docker-compose.yml up -d

# PostgreSQL: add the override file
HUB_PATH=$PWD/my-hub POSTGRES_PASSWORD=<letters and digits> \
  docker compose -f docker/docker-compose.yml -f docker/docker-compose.postgres.yml up -d

Run operator commands inside the container:

docker compose -f docker/docker-compose.yml exec hubzoid hubzoid doctor /hub

Docker deployment covers production settings.

SQLite for scheduled workCopy Anchor Link

On Python 3.12 the workflow engine needs SQLite 3.42 or newer. Python builds that link an older system SQLite (Debian 12, Ubuntu 22.04) cannot run scheduled tasks or workflows, and the bridge logs that the workflow engine did not start. Chat still works, and Python 3.11 is not affected.

Check the SQLite your Python uses:

python -c "import sqlite3; print(sqlite3.sqlite_version)"

If it is older than 3.42, use a Python build with a newer SQLite (python.org, uv, Homebrew, Debian 13, Ubuntu 24.04) or PostgreSQL. On Ubuntu and Debian, install Python 3.12 with sudo apt update && sudo apt install -y python3.12 python3.12-venv git curl.

If something goes wrongCopy Anchor Link

Next stepsCopy Anchor Link