Skip to main content

Architecture overview

kixctl is a Laravel, Livewire, and Filament control plane. It holds authority and keeps its own state in Postgres, and it drives an Incus fabric entirely through the Incus REST API. There are three layers, and the boundaries between them are not crossed.

The three-layer rule​

  1. The control plane decides and remembers — the web application and its Postgres state.
  2. The Incus REST API is the only backend. The control plane never touches the host and never the raw Incus socket; every cluster action is an HTTPS call to Incus.
  3. Incus and the host do the isolation and the privileged work.

The single deliberate exception is nix build, which has to touch the build host. It is isolated in its own audited subsystem, separate from the control plane, so "the control plane talks only to the Incus REST API" holds with no carve-outs. That subsystem and its guarantees are in The build subsystem.

kixctl's state is its own​

kixctl's Postgres holds kixctl's state — users, roles, jobs, sessions, and the per-app configuration it injects into deployments. It is never a synced copy of Incus state. Fleet state is read live from Incus at render time, so what the dashboard shows cannot drift from the cluster: there is no cached mirror to reconcile. This is the same principle that lets the deploy lifecycle keep no revision ledger — what is running is read from Incus, not from a table that could fall out of step. See Rollback and the state boundary.

Two things that follow​

Because the only backend is a documented HTTP API reached over a scoped certificate, two properties hold across the whole system: the control plane cannot escalate its own access to the fabric, and no user-controlled value is ever interpolated into a shell, because there is no shell — every action is a structured API call. Both are architectural, not policies layered on afterward.