Self-hosting overview

The hub is a Cloudflare Worker. Self-hosting means you deploy that Worker, its storage, and its two Durable Object classes to your own Cloudflare account, create a GitHub App and a Slack App that point at it, and pair your agents to it. The agent binary is the same one the hosted service uses.

Architecture

GitHub App ──webhook──▶  Hub (Cloudflare Worker, Hono)  ◀──WebSocket── Agent (your server)
Slack App  ──events───▶    D1 (SQL)  R2 (logs)                          clones the repo,
                           AGENT_DO (one per agent connection)          runs checks,
                           SLACK_DO (one per Slack workspace)           streams results
                           cron every 5 minutes

• The agent dials the hub over a WebSocket at /v1/agent/connect. It needs outbound HTTPS only. There are no inbound ports and no SSH.
• A push or pull request webhook reaches the hub, which routes the job to a paired agent. The agent clones the repository itself with a short-lived installation token.
• Source code is never sent to the hub. Only results, annotations, and logs are.
• The hub reports results as GitHub Check Runs with annotations and posts them to Slack.

What you run

Piece	Where	Purpose
Worker hookci-hub	Cloudflare Workers	HTTP API, webhooks, Slack handlers, cron
D1 database, binding DB	Cloudflare D1	Runs, jobs, agents, installations, tokens
R2 bucket, binding LOGS	Cloudflare R2	Job logs
Durable Object AGENT_DO (class AgentDO)	Cloudflare	One per agent connection
Durable Object SLACK_DO (class SlackDO)	Cloudflare	One per Slack workspace
Cron */5 * * * *	Cloudflare	Periodic maintenance
GitHub App	github.com	Webhooks, check runs, installation tokens
Slack App	api.slack.com	/hookci command, App Home, messages
Agents	Your Linux servers	Run the checks

Requirements

• A Cloudflare account. Check Cloudflare’s current plan requirements for Workers, D1, R2, and Durable Objects before you start.
• Node 22 or newer and Wrangler (npx wrangler --version).
• A domain or a workers.dev hostname for the hub, reachable over HTTPS from GitHub, Slack, and your agents.
• Permission to create a GitHub App and a Slack App.
• openssl to generate random keys.
• One or more Linux servers (amd64 or arm64) for agents.

Checklist

Follow the pages in order.

Step	Page	Done when
1. Cloudflare resources and deploy	Deploy to Cloudflare	The Worker answers on your hub URL
2. GitHub App	GitHub App	Webhook deliveries from GitHub succeed
3. Slack App	Slack App	/hookci help replies in Slack
4. Agents	Connect agents	An agent shows as connected in App Home
5. Operate	Operations	Backups and monitoring are in place

Steps 1 to 3 depend on each other: the manifests need your hub URL, and the Worker needs the secrets the apps produce. The pages note where to deploy first and set secrets after.

Differences from hosted

• You choose the hub URL. Agents connect with hookci connect --hub https://hub.example.com <token> instead of the default hub.
• You create and own the GitHub App and Slack App. Their credentials are your secrets.
• You manage retention, backups, upgrades, and key rotation. See Operations.
• Privacy, data location, and support are yours to define. The hosted terms do not apply.
• Plans and limits from the hosted service do not apply. See Hosted overview for what the hosted hub provides.