Deployment topologies

Every Hubzoid deployment is built from the same three processes. The shapes below differ in how many hubs share them and where the data lives. Pick a shape before you provision a server, because moving between SQLite and PostgreSQL later is a manual step.

When to use thisCopy Anchor Link

Read this page before your first deployment past a laptop, and again when you add a second hub, move to PostgreSQL or put Hubzoid on a container platform. For the step-by-step setup of each shape, follow the links in Next steps.

The building blocksCopy Anchor Link

The bridge never listens on a public interface. Its /v1, /uploads and /healthz routes are reachable only from the same machine, and /v1 also requires a key from BRIDGE_API_KEYS. See the security model for the full list of public and loopback paths.

Supported shapesCopy Anchor Link

The gateway is lighter than one hubzoid run per hub because it starts a single chat app process. It shares one login surface by design. When hubs need separate login realms, run them as separate hubs instead. The gateway page covers its flags and URL layout.

Rules for every shapeCopy Anchor Link

• One bridge per hub. Two processes serving the same hub at once is not a supported configuration. On a container platform, run each hub as its own service with a desired count of 1 and no autoscaling.
• SQLite stays on a local disk. Do not put SQLite files on a network filesystem such as NFS or EFS. File locking over a network filesystem corrupts SQLite databases.
• One SQLite workflow database per hub. In a gateway each hub keeps its own .hubzoid/dbos.db. The gateway refuses to start when a multi-hub deployment points HUBZOID_DBOS_DB at a SQLite file.
• Unique hub folder names. A hub's folder name is its access domain. Within one deployment, names must differ even when compared case-insensitively.
• SQLite 3.42 or newer on Python 3.12. The workflow engine needs it for scheduled tasks and workflows. hubzoid doctor reports it as deps.sqlite. Python builds from python.org or Homebrew, Debian 13 and Ubuntu 24.04 ship a new enough SQLite. PostgreSQL avoids the requirement.

Where data livesCopy Anchor Link

Hubzoid keeps its state in three stores, and the chat app keeps a fourth.

In a standalone hub the operational store and the hub database share one SQLite file. Each store keeps its own schema version table, so they never collide.

Hubzoid resolves each store's URL in a fixed order:

Inside a gateway the manifest (<data-dir>/deployment.json) is authoritative. A bridge or operator command whose HUBZOID_OPERATIONAL_DB or HUBZOID_DBOS_DB disagrees with it stops with an error instead of writing to a second store.

SQLite or PostgreSQLCopy Anchor Link

SQLite is the default and needs no setup. It suits one machine with one bridge per hub, and hubzoid backup copies it consistently while the hub runs.

Choose PostgreSQL when you want a managed database server with its own backups and point-in-time recovery. Install the driver extra and use the postgresql+psycopg:// URL form, because Hubzoid installs the psycopg 3 driver only:

pip install "hubzoid[postgres]"

Hubzoid upgrades its own tables at start. The workflow engine keeps its tables in the dbos schema. Hubzoid does not copy an existing SQLite deployment into PostgreSQL, so start a PostgreSQL deployment fresh or move the data with your own tooling.

Two ways to point Hubzoid at PostgreSQLCopy Anchor Link

For a gateway, set the variables in the environment the hubzoid gateway process starts with:

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

Both variables can name the same database. Hubzoid's tables use an hz_ prefix and the workflow engine uses its own schema.

How sharing one database behavesCopy Anchor Link

The choice between the two forms follows from what each store is keyed on:

• The operational store is shared by design. Every row carries its hub, so one store serves every hub in a gateway. An organization grant made in one hub is visible to all of them, and one Console covers the deployment.
• The workflow engine can share PostgreSQL. Each hub runs under its own application name and queues, so several hubs can use one PostgreSQL system database. On SQLite each hub keeps its own file.
• The hub database is not keyed by hub. It stores WhatsApp and Telegram history per sender (whatsapp-<phone>, telegram-<id>). Hubs that share one DATABASE_URL share this table, so a person who writes to two hubs over the same channel would get one merged history. Keep one hub database per hub, which the HUBZOID_OPERATIONAL_DB and HUBZOID_DBOS_DB form does automatically.
• The chat app follows DATABASE_URL. Hubzoid reads two things directly from the chat app's SQLite file: the per-user API keys that authenticate the hosted MCP server and the chat app groups used by hubs that have not moved to managed grants. Both need the chat app on SQLite, which is why DATABASE_URL suits only the single-hub case in the table above.

Choosing a shapeCopy Anchor Link

Check any shape with hubzoid doctor <hub>. It reads the deployment without changing it and fails on misconfigured or unreachable databases (db.operational, db.hub).

Next stepsCopy Anchor Link

Read this page as Markdown