Skip to content
Kaio

Development setup

This section is for working on Kaio. To run it, see Installation.

Toolchain

Section titled “Toolchain”

  • Nix (recommended). A shell.nix is provided and pins the whole toolchain:

    Terminal window
    nix-shell

  • Alternatively, Rust 1.80+ and Node.js 22+.

Building from source also needs Skopeo on the host, since the update checker shells out to it. The production image already bundles it.

Workspace

Section titled “Workspace”
Terminal window
nix-shell
make install

make install fetches the Rust dependencies (cargo fetch) and installs the frontend packages (npm install).

Start both servers in parallel:

Terminal window
make dev
Process URL Serves
Backend http://127.0.0.1:8080 REST API, SSE streams, WebSocket shells
Frontend http://127.0.0.1:5173 Vite dev server with HMR

make dev runs cargo fmt first and points the backend at sqlite:../data/kaio.db, so the dev database lives in data/ at the repository root.

Make targets

Section titled “Make targets”
Target What it does
make server Backend only
make tui Launch the TUI against a running server
make cli ARGS="stack ls" Run one CLI command
make verify fmt --check + clippy -D warnings + cargo test + tsc --noEmit
make dist The release tarball for this host’s architecture, under dist/
make docs-dev Documentation site with live reload on http://localhost:4321/
make docs-check Reference pages checked against the Rust sources, then a full site build

make verify is the gate to run before pushing; it mirrors what CI checks.

Documentation

Section titled “Documentation”

The site lives in docs/, built with Astro and Starlight. make docs-check runs docs/scripts/check-docs.py, which compares the CLI commands, HTTP routes, environment variables, TUI keys and database tables documented here against the Rust sources, then builds the site. CI runs the same check on every pull request touching the documentation.

Section titled “Related”

Kaio, built by Régis Gaidot