Integration catalog
Browse and install additional curated connectors on the daemon — vault token or PAT when required.
After Slack is connected, the daemon can grow with additional curated catalog entries — connectors shipped as data on the same install → probe → save spine as the rest of the integration catalog. Prefer this path for GitHub and GitLab, which need a vault-backed token or PAT, not a second hosted OAuth mega-product per vendor.
This guide covers the desktop app's Settings → Connections → Integration catalog surface, backed by the local daemon. It is not the web app's Settings → Integrations page, where GitHub and GitLab are connected for plans and Overview. For Slack App registration and OAuth, stay on Slack.
Personal access tokens, PATs, API tokens, and any vault secret never belong in a repository, a brief, a transcript, or these docs. Paste only into the desktop Connections / catalog install flow so the daemon vault encrypts them. Examples below use clearly fake placeholders such as ghp_EXAMPLE_not_a_real_token and glpat-EXAMPLE-not-a-real-token.
What you will do
- Browse the catalog — see curated entries the daemon advertises (beyond fixtures and Slack).
- Install an entry — run install so the daemon probes, then persists the installation.
- Attach a token or PAT when required — entries marked as needing a secret fail closed without one.
- Confirm and remove — check installed state; remove clears the installation (and linked credential).
Prerequisites
- Kairoku desktop able to reach the daemon on the same machine (or a reachable host).
- Daemon running — catalog list/install/remove and vault writes go through the daemon, not the browser web app alone.
- A token minted at the vendor (fine-grained PAT, GitLab access token, and so on) stored in a password manager until you paste it into the install flow.
fixture.* entries are probe fixtures for development and tests. Do not treat them as product connectors.
Browse the catalog
- Open the desktop app → Settings → Connections.
- Open the integration catalog (or catalog section of Connections — same place as install/remove for curated cards).
- Read the list the daemon returns. Each curated row carries an id, display name, and whether a secret is required.
The catalog is compiled into the daemon (kairokud) as data. This release's curated entry ids are slack, github, and gitlab; the daemon also ships fixture.echo, fixture.fail, and fixture.secret as probe fixtures for development and tests, never product connectors. Each row carries an id, a display name, and whether it requiresSecret — github and gitlab do, slack is connected through the Slack card instead (see Slack).
The list is headed Catalog version 2 — the number is the catalog data version, not the daemon version. To try a different catalog — for testing an entry before it ships — set KAIROKUD_INTEGRATION_CATALOG=<path to a JSON file> before starting the daemon; the file replaces the compiled-in list entirely.
Install a curated entry
For an entry that does not require a secret:
- Choose the catalog card (for example GitHub or GitLab when listed).
- Run Install (or the equivalent action the card shows).
- Wait for probe → save. On success the entry appears under installed integrations; on probe failure install fails closed — nothing is left half-installed.
The probe in this release is a fixed result per entry — it does not call the vendor. A successful install means the entry and its secret were stored, not that the token is valid; a bad PAT surfaces later, wherever it's actually used, not at install time. Failed probes still fail closed — fixture.fail demonstrates this — so nothing is left half-installed and the entry is absent from the installed list.
Slack is connected through the Slack card, not through this catalog install path — its token reaches the vault by the route Slack describes. Do not invent a per-vendor hosted OAuth App for every new catalog row.
Token / PAT when required
When the catalog marks an entry requiresSecret (or the card asks for a token / PAT):
- Mint a read-scoped credential at the vendor — prefer the narrowest token that matches what the card describes (contents / API read, not blanket admin).
- Paste it only into the install field the Connections UI provides. Shape-only examples:
ghp_EXAMPLE_not_a_real_token,glpat-EXAMPLE-not-a-real-token. - Confirm install. Missing or rejected secrets fail closed — the entry must not appear as installed.
- A stored secret is never rendered back. To rotate, remove the installation and install again with a new token.
Tokens live encrypted in the daemon vault on the box. The UI configures; it is not a second plaintext secret store.
Where the vault lives: credentials are encrypted with ChaCha20-Poly1305. The master key sits in ~/.kairoku/daemon/.secrets.json, mode 600 — a file on disk, not the OS keychain; set KAIROKUD_SECRETS_FILE to move it. integration.credentials.* holds this vault, and a catalog install attaches a credential id to the entry it secures. List and get calls never return plaintext — the wire shows ******** — so rotating a secret means removing the installation and installing again, not editing a value in place.
After install
| Check | Expect |
|---|---|
| Catalog / Connections card | Entry shows installed; no token value visible |
| Daemon | Running; installation survives desktop restart while the daemon keeps its data |
| Remove | Clears the installation and any linked vault credential for that entry |
| Web Integrations | Unchanged — installing a catalog github / gitlab entry is not the same as connecting GitHub or GitLab in the web app's Settings → Integrations |
Shipped alongside
This release also shipped, outside this catalog surface:
- A visual graph builder for playbooks, in the web app — see Workflows.
- A Slack wake relay that queues events while your daemon is offline — see Slack.
- Cross-daemon automation routing across multiple daemon hosts — see Automations.
Related
- Connections — GitHub and GitLab in the web app (read path for plans)
- Desktop app — the app and local daemon this catalog runs on
- Slack — App registration, OAuth, Teammate grants
- Teammates — grants that ride the same daemon
- Automations — cron, signed webhooks, forge wakes (no forge credential; not catalog install)
- CLI — daemon install on the machine