Single server

hubzoid run <hub> is the production entry point for a hub. On a server you wrap it in systemd, keep every Hubzoid port on loopback, and let a reverse proxy you already trust terminate TLS on port 443. The walkthrough below uses Ubuntu 24.04. The same steps work on Debian and RHEL-family systems with the package manager swapped.

When to use thisCopy Anchor Link

Use this setup for one to a few hubs on a single Linux machine, each with its own chat app and URL. It is the simplest and cheapest production shape. If several teams should share one sign-in and one Console, run a multi-hub gateway instead. If pip install is impractical on the host, use Docker.

As a starting point, plan for 2 GB of memory for one hub and 4 GB for two or three hubs on the same machine.

What runsCopy Anchor Link

hubzoid run starts and supervises these processes. When the bridge exits, the command stops the others.

The edge is the only process your proxy talks to. It serves these public paths:

The bridge's /v1, /uploads and /healthz routes are never forwarded. The edge also refuses . and .. path segments and drops client-sent X-Hubzoid-* and X-OpenWebUI-* headers.

Deploy a hubCopy Anchor Link

sudo apt update && sudo apt install -y \
  python3.12 python3.12-venv pkg-config ffmpeg 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-hub-agents.git agents
cd agents
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cd /opt/hubzoid/agents/devops-agent
touch .env && chmod 600 .env

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

WEBUI_AUTH=true
WEBUI_SECRET_KEY=<openssl rand -hex 32>
WEBUI_URL=https://devops.agents.example.com

PORT=3080
BRIDGE_PORT=8000

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

[Service]
Type=simple
User=hubzoid
Group=hubzoid
WorkingDirectory=/opt/hubzoid/agents
ExecStart=/opt/hubzoid/agents/.venv/bin/hubzoid run %i
# claude-local calls the `claude` CLI, which the default systemd PATH misses.
Environment=PATH=/opt/hubzoid/.local/bin:/usr/local/bin:/usr/bin:/bin
Restart=always
RestartSec=10s
TimeoutStopSec=30
StandardOutput=journal
StandardError=journal

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@devops-agent
journalctl -u hubzoid@devops-agent -f

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

sales.agents.example.com {
    reverse_proxy 127.0.0.1:3081 {
        flush_interval -1
        transport http {
            read_timeout 600s
        }
    }
}

/opt/hubzoid/agents/.venv/bin/hubzoid doctor /opt/hubzoid/agents/devops-agent

Public URLs for download linksCopy Anchor Link

Files the agent makes are served at /artifacts/... through the edge. The link's base address comes from HUBZOID_PUBLIC_URL, then WEBUI_URL, then http://127.0.0.1:<BRIDGE_PORT>. Behind a proxy, WEBUI_URL is usually enough. Set HUBZOID_PUBLIC_URL only when downloads must use a different public address.

Links are signed with a per-hub secret in .hubzoid/artifact_secret. They never expire unless you set HUBZOID_ARTIFACT_LINK_TTL in seconds.

Several hubs on one serverCopy Anchor Link

Repeat the .env step for each hub with its own PORT and BRIDGE_PORT, then enable another instance of the same unit:

sudo systemctl enable --now hubzoid@sales-agent

Each hub has its own chat app, user list and URL. To give several teams one sign-in and one Console instead, use a gateway.

Scheduled workCopy Anchor Link

Markdown tasks in schedule/*.md run whenever their files exist (HUBZOID_DISABLE_SCHEDULE=1 turns them off). Code workflows in workflows/ are scheduled on a standalone hub only when its environment sets HUBZOID_SCHEDULES=1. A gateway turns this on for every hub. See operating runs.

Running on a Claude subscriptionCopy Anchor Link

MODEL=claude-local runs inference through the claude CLI on a Claude Pro or Max subscription. On a server, mint a long-lived token on any machine signed in to the subscription with claude setup-token, and put it in the hub's .env as CLAUDE_CODE_OAUTH_TOKEN. 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.

Slack and inbound channelsCopy Anchor Link

The Slack adapter uses Socket Mode, so it needs no public route. Run it as its own unit so a Slack problem never restarts the chat app:

hubzoid slack systemd /opt/hubzoid/agents/devops-agent \
  --python /opt/hubzoid/agents/.venv/bin/python \
  --user hubzoid \
  | sudo tee /etc/systemd/system/hubzoid-slack@devops-agent.service

hubzoid inbound systemd <hub> prints the equivalent unit for WhatsApp, Telegram and webhook surfaces. See Slack and WhatsApp and Telegram.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link

Read this page as Markdown