kairokud as a runner
Linking the Rust daemon, kairokud, to your account so it shows under Machines and claims Floor runs — what is published, how the link works, and what kairokud doctor checks.
kairokud is the Rust daemon — the one the desktop app carries. Linked to your Kairoku account, it is also an agent-machine runner: it heartbeats to the API, shows under Settings → Developers → Machines, and claims Floor dispatches over the same /api/daemon/* routes as the CLI's kairoku daemon (Runner setup). On a mac it is the only service form — kairoku daemon install refuses there, because the io.kairoku.daemon LaunchAgent belongs to kairokud.
What is published
Each kairokud release is published on the distribution project's Releases page as two releases:
| Release | Archive | What it is |
|---|---|---|
daemon-vX.Y.Z | kairokud-<target>.tar.xz | The daemon: the kairokud binary and the adapters/ directory it launches coding agents through |
sitter-vX.Y.Z | kairokud-<target>.tar.xz | The sitter: a supervisor, also named kairokud, that runs the daemon from its versioned directory and restarts it if it exits |
Both carry four targets — aarch64-apple-darwin and x86_64-apple-darwin for macOS, x86_64-unknown-linux-musl and aarch64-unknown-linux-musl for Linux — each with a .sha256 file beside it.
There is no Windows build. No release carries a Windows archive.
A bare archive is not a supported install: the daemon looks for its adapters/ in its versioned directory, which the installer creates.
Install it (macOS and Linux)
curl -fsSL https://gitlab.com/owds-inc/releases/kairoku/distribution/-/raw/main/install-kairokud.sh | shThe installer:
- Reads the stable channel,
channels/kairokud-stablein the distribution project, and downloads that version's sitter and daemon archives for your OS and CPU. Each is checked against its.sha256file before anything is installed. - Installs the sitter as
kairokudin/usr/local/binwhen that is writable, otherwise~/.local/bin.KAIROKUD_INSTALL_DIRpicks another directory. - Installs the daemon and its
adapters/to~/.kairoku/daemon/sitter/versions/<version>/, and records that version in~/.kairoku/daemon/sitter/state.json. - Asks whether to run
kairokudas a per-user service that starts at login (a launchd LaunchAgent,io.kairoku.daemon, on macOS; a systemd user unit on Linux) and to start it now. Answer yes. Service setup also writes the installation record thatkairoku setup --daemon --linklooks for.
The question is read from the terminal, so it works through curl … | sh. Where there is no terminal, the installer skips service setup; set KAIROKUD_INSTALL_SERVICE=1 to set it up without asking:
curl -fsSL https://gitlab.com/owds-inc/releases/kairoku/distribution/-/raw/main/install-kairokud.sh | KAIROKUD_INSTALL_SERVICE=1 shWith the service set up, the installer waits until kairokud status answers, then prints how to manage the service. It needs curl or wget, tar, and on Linux xz. On a headless Linux machine a user service starts at boot only with lingering on (KAIROKUD_PROFILE=linux-server, or sudo loginctl enable-linger $USER).
Run the same command again to upgrade; a running service switches to the new version when it restarts. KAIROKUD_VERSION=X.Y.Z installs that published version instead of the channel's.
The host needs git (workspace provisioning shells out to it) and Node.js with npm/npx (several coding-agent CLIs are npm packages or pinned npx launches). gh is optional — the daemon takes its GitHub token from the app's GitHub connection first, then GITHUB_TOKEN/GH_TOKEN, then gh auth token. Data lives under ~/.kairoku/daemon/ unless KAIROKUD_DATA_DIR says otherwise; the installer and the service follow it.
Link it to your account
On the machine, with kairokud on PATH and running, and the Kairoku CLI installed:
kairoku setup --daemon --linkWhen the CLI finds a kairokud installation, it enrols it:
- It asks the API for an enrolment request for this installation — machine name, OS, architecture and profile — and prints a code and a link to the app's
/linkpage. - Open the link, signed in, check the code, and press Approve. The page shows the code, the machine, OS and architecture, profile, installation id and the owning account. The request expires after ten minutes.
- The CLI hands the credential to
kairokudover stdin (kairokud settings kairoku.token --stdin— never on the command line), runskairokud link acknowledge, then waits forkairokud status --jsonto show the same installation, daemon and owner with a heartbeat that succeeded.
Only then does it print Rust enrolled — daemon …, owner …. Anything short of that stops with the reason and account setup is incomplete — rerun kairoku setup --daemon --link to resume; a rerun picks up the same request. Enrolment refuses a backend that is not HTTPS, and refuses to move a linked installation to a different account unless kairokud status proves it idle.
The daemon talks to https://api.kairoku.io. KAIROKUD_LINK_ENDPOINT points it elsewhere, and KAIROKUD_LINK_ENABLED=false turns the link off. kairokud link status prints linked or unlinked, and kairokud link unlink removes the stored credential.
kairoku enroll --backend-url <url> --data-root <absolute-path> enrols an existing installation in a non-default data directory without touching anything else; KAIROKUD_DATA_DIR must equal --data-root.
With no kairokud installation on the machine, --link takes a different path: it opens /link from a loopback listener and writes KAIROKUD_LINK_TOKEN into ~/.kairoku/token.env. kairokud reads its credential from its own secrets store, not from that file, so that path does not link a running kairokud.
Check it under Machines
Settings → Developers → Machines lists the machine within a heartbeat. Its liveness reads online, stale or offline — the same windows as any runner. Expand it for Machine, Capacity, Last heartbeat, Registered, Teams, and Repositories.
Each repository carries an access badge from the daemon's own probe (kairokud 1.1.3 and later), sent with its heartbeat. The probe covers the GitHub repositories of your projects, runs every 15 minutes against the GitHub API with the same token a clone would use, and never reports the token. Hover a badge for when it was checked and, where it failed, why.
| Badge | Meaning |
|---|---|
| Can push | Reachable, credentials accepted, push allowed |
| Read only | Reachable and readable, but this machine cannot push — runs cannot open a pull request |
| Can read | Reachable and readable; push was not determined |
| No access | Reachable, but the credentials were refused |
| Unreachable | The repository could not be reached |
| Not checked | No probe result yet |
No access and Unreachable make a repository unusable on that machine: the collapsed row says n repos need access, and the machine picker in the run dialog disables it with can't access <repo>. Read only is a limit, not a block — the picker still offers the machine, marked read-only on <repo>.
kairokud doctor
kairokud doctor # local only, no network call
kairokud doctor --link # plus one live heartbeat and the per-repo access probe
kairokud doctor --providers # plus an offline start of the three bundled agent adaptersEach line is [ok], [--] (a warning) or [FAIL], and the last line is kairokud doctor: OK (n warnings) or kairokud doctor: FAILED — <reasons>, with a nonzero exit on any FAIL. In order:
| Line | What it checks |
|---|---|
| config.toml parsed | The daemon's config parses. A config that does not is FAIL and doctor stops there |
| data dir writable | The data directory accepts writes |
| sqlite openable, migrations current | The database opens and every migration is applied |
| control socket bindable | The local socket is free. FAIL when it is occupied — stop the running daemon before a full check |
| providers | Which coding-agent providers resolve on this host. Warnings only |
| providers probe | With --providers, starts each bundled adapter offline and reports n/3 initialised. Skipped otherwise |
| link | link: unlinked or link: linked from the stored credential. With --link: linked <name> · last beat …, token rejected, or unreachable (…). FAIL only when the secrets store is corrupt |
repo (with --link, 1.1.3 and later) | One line per GitHub repository of your projects: [ok] repo <owner/name>: reachable, auth ok, can push (or cannot push, push unknown); [--] … reachable, auth failed; [FAIL] … unreachable. These are the facts behind the badges above |
| WSS port, TLS cert | The remote-client port and certificate. Warnings only |
| GitHub token | Whether GITHUB_TOKEN/GH_TOKEN is set, or gh is on PATH. Presence only — never the value |
| host | OS, architecture and whether a display is attached |
| CoW isolation | Whether the workspaces directory supports copy-on-write clones. Unsupported is a warning: workspaces fall back to shared mode |
kairoku doctor, from the CLI, also reports on a kairokud on the same machine: the installation record, health and versions, and a cloud link row. See CLI.