Cix
Systems, directly.
The Cix source is free software under the GNU General Public License,
version 3, or (at your option) any later version
(GPL-3.0-or-later).
Contributions follow the DCO-based contribution guide; the
Cix name and marks are governed separately by TRADEMARK.md.
Cix OS is a rolling-release hardware and workload orchestration platform, compiled entirely from source: a hand-rolled container runtime on raw Linux namespaces and cgroups, image layering by btrfs snapshot, a 100% custom C networking data plane, and a REST control layer for the host, containers, hardware, disks, networks, DNS, PKI, and more — no runc, no Open vSwitch, no eBPF-based networking dataplane. Cix's own code is compiled exclusively with the Tiny C Compiler (TCC); third-party packages build with TCC by default and with Cix's own self-hosted gcc where TCC cannot (ADR-0224, ADR-0226). Every capability, including hardware itself, is a first-class API resource; containers are where all real work happens, the host is the thinnest possible layer underneath them. Full charter: docs/mission/MISSION.md.
Versioning
A release is <version>-<release>: the version is 0.2.x, and the release is the counter. 0.2.57-358, then 0.2.57-359.
The git tag, the build version cixctl boot reports, the os-release BUILD_ID, the recipe identity (version "0.2.57" + release 358) and the artifact name are one string, spelled identically, with no v prefix — 0.2.57-358.
The leading 0 is not modesty, it is accurate: Cix has not shipped a stable interface, so it has not shipped a 1.0. Rolling-release means there are no curated milestones to number — git tag --sort=v:refname is the list of releases, and CHANGELOG.md says what each one changed. The reasoning, and what the previous scheme cost, is in ADR-0312.
The Name
Cix — pronounced six. Two halves, each naming a real part of what this is:
| Part | Principle |
|---|
| C | Both meanings are literal here. The core is hand-rolled C all the way down — the container runtime, the networking data plane, the REST control layer — compiled exclusively with the Tiny C Compiler; C is not an implementation detail, it is the product. And containers are where all real work happens, with the host as the thinnest possible layer underneath them. |
| ix | For POSIX and UNIX: direct Linux primitives, exposed rather than wrapped. Raw namespaces and cgroups, btrfs snapshots, rtnetlink — no runc, no Open vSwitch, no bundled platform services. It exposes the kernel, not an opinion. |
The name is the architecture, not a label bolted on afterward. Its full brand system — strategy, voice, colour, typography, the mark and the UI icon set — lives in docs/brand/, with brand-guidelines.md as the authority.
What It Represents
Cix OS is more than a distribution — it's a discipline. Complex routing protocols, VPNs, and container infrastructure are built systematically, one pristine layer at a time, with no hacks and no bypasses. It exists to prove that a completely unified, custom C-based stack can be more reliable than a patchwork of legacy components.
Documentation
docs/README.md is the index to the entire documentation set — start there if you're not sure which document has what you're looking for. docs/guides/quickstart.md is the fastest real path from nothing to a running container.
See docs/roadmap/ROADMAP.md for the full part-by-part history — what shipped, how each was verified. Architecture diagram: docs/architecture/architecture.md. API contract: docs/api/openapi.yaml, with a narrative walkthrough at docs/api/README.md. Why a given significant, hard-to-reverse decision was made: docs/adr/.
Getting started
- Build it:
docs/guides/building-cix.md — self-hosted, on a running Cix box, by the cix recipe.
- Install it:
docs/guides/installing.md — the installer ISO, disk partitioning, Secure Boot. docs/guides/quickstart.md takes a fresh install to a first running container.
- Use it:
docs/guides/cli-reference.md (the cixctl command surface) and docs/guides/web-dashboard.md (the browser UI) — both pure REST clients over the same API documented in docs/api/README.md.
- Run workloads:
docs/guides/containers-and-services.md (containers and deployments), docs/guides/images.md (what a container runs from), and docs/guides/network-services.md (DNS, DHCP, NTP, syslog).
- Administer it:
docs/guides/administration.md (monitoring, backup/restore, disks), (disks, roles, filesystems), (networks, routing, VLANs), (PKI, HTTPS, LDAP accounts), and (wiping and reinstalling a host).
Repository Layout
include/ runtime library public API (container.h) and internal glue
src/ runtime implementation (cgroup, namespaces, mounts, btrfs, container networking)
netplane/ custom rtnetlink control plane (bridges, veth, routes — no ip/iproute2, no OVS)
daemon/ cixd: the REST daemon — the only process with direct runtime/network/DNS/PKI access
client/ shared HTTP client library used by the CLI and the daemon's own test suite
cli/ cixctl: pure REST API client, no direct runtime access
web/ browser dashboard: vanilla HTML/CSS/JS, no framework, no bundler, served by cixd; web/api.js is generated from openapi.yaml by apigen
image/ bare-metal boot tooling: kernel config, mkbootroot, cix-install, mkinstalleriso
init/ cix-init: PID 1 in every container, freestanding (no libc) — the one exception to the TCC-and-glibc rule
tools/ developer tooling: apigen (generates the API surface from openapi.yaml), verify-symbols.sh (link-level symbol checks),
dashboard-screenshot.py (authenticated dashboard screenshots)
test/ the test suite: per-feature tests, contract gates, and the subset the release selftest runs
docs/ all documentation — see docs/README.md, which indexes every subdirectory
build/ compiled output (gitignored)
build-inputs/ hand-fetched build inputs that `make` does not reproduce (gitignored): the Phase 11 kernel bzImage, the test floor's package artifacts
