Single server

At the end of this guide your Hub runs on a Linux server under systemd, people sign in at an HTTPS address, and you are its first administrator with two-step sign-in set up. The steps use Ubuntu 24.04. Debian and RHEL-family systems work the same way with their own package manager.

hubzoid run is the production entry point, the same command you use on a laptop. On a server you wrap it in systemd, keep every Hubzoid port on loopback, turn sign-in on, and let a reverse proxy you already trust terminate TLS.

What you needCopy Anchor Link

• A Linux server with at least 2 GB of memory for one Hub, or 4 GB for two or three. There is no certified maximum, so size it for your workload.
• A DNS name for the Hub, such as kestrel.example.com, pointing at the server.
• Your Hub in a git repository, with a requirements.txt that pins the release you tested, for example hubzoid==<version>.
• A model provider key, or a Claude subscription token (see running on a Claude subscription).

Deploy a hubCopy Anchor Link

sudo apt update && sudo apt install -y python3.12 python3.12-venv build-essential git curl
sudo useradd -r -m -d /opt/hubzoid -s /bin/bash hubzoid

sudo -iu hubzoid
git clone git@github.com:your-org/your-hubs.git agents
cd agents
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

hubzoid version

cd /opt/hubzoid/agents/my-hub
touch .env && chmod 600 .env

MODEL=anthropic/claude-haiku-4-5
ANTHROPIC_API_KEY=<your key>
BRIDGE_API_KEYS=<output of openssl rand -hex 32>

HUBZOID_AUTH=true
HUBZOID_PUBLIC_URL=https://kestrel.example.com
HUBZOID_ADMIN_EMAIL=sam@example.com
HUBZOID_ADMIN_PASSWORD=<at least 8 characters>

cd /opt/hubzoid/agents/my-hub
sudo /opt/hubzoid/agents/.venv/bin/hubzoid service install --port 3080 --user hubzoid --write

[Unit]
Description=Hubzoid
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/hubzoid/agents/my-hub
ExecStart=/opt/hubzoid/agents/.venv/bin/hubzoid run --port 3080 --host 127.0.0.1 --no-open
Restart=always
RestartSec=5
KillMode=mixed
TimeoutStopSec=180
User=hubzoid
# claude-local calls the `claude` CLI, which the default systemd PATH misses.
Environment=PATH=/opt/hubzoid/.local/bin:/usr/local/bin:/usr/bin:/bin
OOMPolicy=stop
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
# Hubs keep state under agents/, and claude-local writes under ~/.claude.
ReadWritePaths=/opt/hubzoid
# ProtectHome stays off: hiding ~/.claude breaks MODEL=claude-local.
ProtectKernelTunables=true
ProtectKernelModules=true
RestrictSUIDSGID=true
LockPersonality=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now hubzoid
journalctl -u hubzoid -f

✓ Hubzoid is ready: https://kestrel.example.com  (sign-in on)

kestrel.example.com {
    reverse_proxy 127.0.0.1:3080 {
        flush_interval -1
        transport http {
            read_timeout 600s
        }
    }
}

/opt/hubzoid/agents/.venv/bin/hubzoid doctor /opt/hubzoid/agents/my-hub

Several Hubs on one serverCopy Anchor Link

To give several teams one sign-in and one Settings page, list the Hubs in a hubzoid.yaml in the folder above them and run that folder with the same single unit. See several Hubs.

To keep Hubs fully separate, with their own accounts and URLs, run one hubzoid run per Hub. Give each Hub its own PORT and its own unit name. hubzoid service install prints the unit, followed by two lines of advice, when you leave out --write. Save only the unit:

cd /opt/hubzoid/agents/sales-desk
/opt/hubzoid/agents/.venv/bin/hubzoid service install --port 3081 --user hubzoid \
  | sed '/^Save it as/,$d' | sudo tee /etc/systemd/system/hubzoid-sales-desk.service
sudo systemctl daemon-reload
sudo systemctl enable --now hubzoid-sales-desk

Bridge ports are picked for you, skipping any port already in use. Add a second site block to the proxy for port 3081.

Running on a Claude subscriptionCopy Anchor Link

MODEL=claude-local runs the agent through the claude CLI on a Claude Pro or Max subscription instead of a metered key. On a server:

1. On any machine signed in to the subscription, run claude setup-token. It prints a long-lived token.
2. Put it in the Hub's .env as CLAUDE_CODE_OAUTH_TOKEN, next to MODEL=claude-local.
3. Install the claude CLI as the hubzoid user, so it is on the unit's PATH. The unit above already keeps the service user's home writable for the CLI's session files.

Heavy automated use shares the subscription's limits with interactive use.

Claude credential failoverCopy Anchor Link

You can add up to two backup tokens beside the primary one:

CLAUDE_CODE_OAUTH_TOKEN=<primary credential>
CLAUDE_CODE_OAUTH_TOKEN_SECONDARY=<first backup>
CLAUDE_CODE_OAUTH_TOKEN_TERTIARY=<second backup>

Hubzoid moves to the next token only when Claude reports a usage limit or rejects the login. The model, the Hub, the caller and their tools stay the same.

Slack and inbound channelsCopy Anchor Link

A channel turns on with a file in the Hub's channels/ folder, never a flag. It starts and restarts with its Hub, so it needs no unit of its own. The Slack adapter uses Socket Mode and needs no public route:

version: 1
id: slack-assistant
provider: slack_assistant
enabled: true

SLACK_BOT_TOKEN and SLACK_APP_TOKEN stay in the Hub's .env. WhatsApp, Telegram and generic webhooks use provider: whatsapp_inbound, telegram or webhook, arrive on the public port at /webhooks/<hub>/..., and are served by the inbound server. A channel whose settings are missing stays off, and the start names what is missing. Follow its output with hubzoid logs my-hub -f. See Slack and WhatsApp and Telegram.

Scheduled workCopy Anchor Link

Markdown tasks in schedule/ run whenever their files exist. Code workflows in workflows/ start on their own on a standalone Hub only when its environment sets HUBZOID_SCHEDULES=1. A deployment that hubzoid run starts from hubzoid.yaml or with several Hubs turns this on for every Hub. Named webhooks that start workflows are received either way. See operating runs.

Download linksCopy Anchor Link

Files the agent makes are served at /artifacts/... through the edge, on links built from HUBZOID_PUBLIC_URL. Each link is signed with a per-Hub secret in .hubzoid/artifact_secret and expires after 7 days. HUBZOID_ARTIFACT_LINK_TTL sets the lifetime in seconds, and 0 means never. The signed-in owner of a conversation can always download its files.

Hubzoid removes one-time sign-in link tokens and OAuth codes from its own access logs. Your proxy logs them unless you redact the /api/auth/link/ path and the token, code and state query parameters, so treat its logs as sensitive.

If something goes wrongCopy Anchor Link

Next stepsCopy Anchor Link