Self-host the hub: Connect agents

Self-host the hub

Connect agents

Install the agent, pair it with your own hub, and validate repository config against self-hosted rules.

The agent is the same binary as for the hosted service. The only difference is the hub URL you give it.

Install the agent

The install script is served by the default hub. If you mirror releases, set HOOKCI_RELEASE_BASE. See Install for all install options.

curl -fsSL https://ci.webuno.io/install | sh

Check the open-source install page and the repository’s install script if you want the installer to come from your own hub or mirror.

Get a pair token

A pair token starts with hc_pair_, is single use, and is valid for 15 minutes. Create one in either place:

  • Slack App Home, then Add agent.
  • The page your hub shows after you install the GitHub App.
Illustration. The hub page after installing the GitHub App, showing a pair token and waiting for the agent.

Pair

  1. On the server, run connect with your hub URL and the token.

    sudo hookci connect --hub https://hub.example.com hc_pair_EXAMPLE

  2. The command redeems the token, writes /var/lib/hookci/<installation-id>/agent.json (mode 600), and starts hookci-agent@<installation-id>.service.

  3. Check that the agent shows in Slack App Home with a connected status dot.

Useful flags: --name NAME, --state-dir DIR, --force, --no-service.

ci-server
ci-server recording
$ sudo hookci connect --hub https://hub.example.com hc_pair_EXAMPLE
ok paired, service hookci-agent@ci-server started
$ hookci doctor
ok hub reachable

Illustration. Pair an agent with a self-hosted hub, then check the host.

The output above is an illustration. Real output differs by version.

Validate repository config

In each repository, lint .hookci.yml with the stricter self-hosted rules.

hookci validate --self-hosted

Add --json for machine-readable output. Exit code 0 means valid.

Troubleshooting

  • Run hookci doctor first. It checks systemd, cgroups, the user, network, and hub reachability.
  • The agent needs outbound HTTPS (port 443) to your hub URL.
  • Pair token expired: create a new one.
  • Status and logs: systemctl status hookci-agent@<installation-id> and journalctl -u hookci-agent@<installation-id> -f.
  • Revoking an agent in Slack App Home makes it exit with code 3, and the unit does not restart.

Next: Operations.