Installation
Install Hubzoid with pip, from source or as a Docker image, add PostgreSQL support, and confirm the install with the doctor command.
One package contains everything hubzoid run needs: the bridge, the three agent runtimes (OpenAI Agents SDK, Claude Agent SDK and local Codex), LiteLLM model routing, the bundled Open WebUI chat app, the channel adapters, the durable workflow engine (DBOS), the hosted MCP server and the Console. There are no optional extras for the runtime itself.
Requirements
| Requirement | Detail |
|---|---|
| Python | 3.11 or 3.12. Newer versions do not work because the bundled Open WebUI requires Python 3.12 or older. |
| Operating system | macOS or Linux for a native install. Any host that runs Docker for the image. |
| Memory | 2 GB RAM for one Hub on a server, 4 GB for two or three Hubs on the same machine. |
| SQLite | On Python 3.12, the workflow engine needs SQLite 3.42 or newer. See platform notes. |
| Model access | The claude CLI logged in to a Claude subscription, the Codex CLI 0.147.0 logged in to a Codex account, or an API key for OpenAI, Anthropic, Azure OpenAI or OpenRouter. The CLIs are installed separately. See the quickstart and agents and models. |
Install
Create a virtual environment with Python 3.11 or 3.12 and install the package from PyPI.
python3.12 -m venv .venv
source .venv/bin/activate
pip install hubzoid
hubzoid versionhubzoid version prints the installed version. python -m hubzoid works anywhere the hubzoid command does.
To store Hubzoid's data in PostgreSQL instead of SQLite, install the postgres extra. It adds the psycopg 3 driver.
pip install "hubzoid[postgres]"Then point the Hub (or the gateway and every bridge) at the database with the postgresql+psycopg:// form of the URL:
DATABASE_URL=postgresql+psycopg://hubzoid:<password>@db.internal:5432/hubzoidWith DATABASE_URL set, Hubzoid's own hz_* tables, the workflow engine's dbos schema and Open WebUI's tables share that database, and each owner upgrades its tables at start. Deployment topologies explains when to choose PostgreSQL.
The image listens on all interfaces
The image sets HUBZOID_HOST=0.0.0.0, so the published port accepts connections from other machines. Turn on sign-in before anyone else can reach it. Authentication covers the settings.
Platform notes
macOS. The default python3 on recent macOS is newer than 3.12. Create the virtual environment with python3.12 -m venv explicitly. If pip starts building av (PyAV) from source, install its build dependencies first:
brew install pkg-config ffmpegUbuntu and Debian. Install Python 3.12 and the PyAV build dependencies:
sudo apt update && sudo apt install -y \
python3.12 python3.12-venv pkg-config ffmpeg build-essential git curlSQLite for scheduled work. 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. Use a Python build with a newer SQLite (python.org, Homebrew, Debian 13, Ubuntu 24.04) or PostgreSQL. Chat is not affected. hubzoid doctor reports this as the deps.sqlite check.
Verify the install
hubzoid doctor checks a Hub and its deployment without changing anything. Run it against any Hub folder, for example the one hubzoid init creates in the quickstart:
hubzoid init my-hub
hubzoid doctor my-hubEach line shows a status mark, a summary and a stable check id. The command exits with code 1 when any check fails, so it also works in scripts and CI. --json prints the same checks as JSON.
| Check id | What it confirms |
|---|---|
hub.agents_md | AGENTS.md exists at the Hub root. |
runtime.build | The agent builds with its tools, skills, knowledge and connectors. |
deps.versions | Installed versions of Hubzoid, Open WebUI, DBOS, LiteLLM and the agent SDKs. |
deps.sqlite | The SQLite build can run the workflow engine. |
auth.bridge_keys | BRIDGE_API_KEYS is set and is not the public default dev. |
auth.chat_signin | Whether chat sign-in is on. Off is reported as information on a local-only Hub and as a failure when the port is exposed. |
model.credentials | The configured model has credentials: a provider key, CLAUDE_CODE_OAUTH_TOKEN, or a claude login. |
hubzoid init writes a random bridge key into .env, so auth.bridge_keys passes on a new Hub. The doctor reference lists every check.