Client surfaces
Clients have no special access.
cixctl, the vanilla HTML/CSS/JS dashboard, and the physical console all use the same API. The OpenAPI document is the contract for other integrations.
System architecture
One control path.
Visible end to end.
The CLI, web dashboard, and physical console converge on a REST-first native C daemon. From there, Cix reaches Linux primitives directly.
Control plane
cixd is the authority.
A single-threaded, non-blocking epoll reactor written in C and compiled with TCC. It is the only process linked directly to the container runtime and the only process with direct runtime, network, DNS, PKI, LDAP, and package access.
Runtime mechanisms
Linux mechanisms stay recognisable.
Namespaces + cgroupsclone3(), PID namespaces, mount namespaces, cgroup v2, and pidfds.
OverlayFSOne shared read-only image lowerdir plus per-container upper and work directories.
Rtnetlink + nl80211Custom C networking speaks directly to the kernel for wired links, routes, and whole wireless radios—no OVS and no eBPF data plane.
Device grantsReal device nodes, shared-ownership checks, and cgroup device filters expose explicitly assigned hardware.
Workloads
Containers carry supervised services.
Each deployment names an image and receives its own namespaces, cgroup, filesystem diff, network attachments, limits, configuration, and optional hardware. If its image is not ready, the deployment waits while the shared pipeline converges it. Container-visible /proc reports limits and usage. A container declares services[]; freestanding cix-init supervises them, while the API exposes derived readiness and per-service lifecycle actions.
Host OS
Write, verify, cut over.
Cix boots a kernel.org Linux kernel with cixd as PID 1 and no initramfs. Operators choose a pinned, longterm, stable, or mainline tracking policy through the API; policy reports the available version and never silently moves the recipe pin. The control-plane root is read-only squashfs. Host updates target the inactive A/B slot, verify it, and let Cix’s own EFI boot manager provide counted rollback. The same host can build the Cix Build System and its native zstd/libarchive dependencies; CBS integration into cixd remains outside this boundary.
ACTIVESlot Aread-only · serving
→NEXTSlot Bwrite · verify · boot
Readable overview
From declared intent to a running system.
This view makes the ownership boundaries explicit: cixd validates API intent, host state stays authoritative, provider containers render services, and workloads receive controlled Linux primitives. The repository diagram carries the detailed paths, storage layout, boot chain, and ADR references.
The layer-by-layer explanation above is the equivalent text alternative.
Open source diagram ↗
