Axis

Axis

Axis is a system for constructing and operating immutable Linux-based systems. Its architecture has three subsystems with separate responsibilities.

Subsystems

Subsystem	Responsibility	Contract
Build System	Construct reproducible software and system images from explicit inputs.	Build System
Base OS	Define the immutable operating-system format and its boot and runtime boundary.	Base OS
axisd	Initialize and manage a running Linux system as its first userspace process.	axisd

These are the concepts at this level. Their internal models and implementation mechanisms belong to their own specifications.

Collaboration

The Build System can produce images conforming to the Base OS contract. It also supports construction that does not require that contract. Operating an image and constructing it are separate activities.

The Base OS defines the conditions under which execution reaches its runtime. axisd accepts those conditions, establishes the runtime environment and remains responsible for the running system. How the Build System constructs an image does not change this runtime boundary.

flowchart LR
    Construction["Build System"]
    Contract["Base OS"]
    Runtime["axisd"]
    Construction -->|produces conforming systems| Contract
    Contract -->|defines entry conditions| Runtime
    class Runtime program

Application wiring

The axis command is the user-facing application. It supplies distribution defaults, invokes construction and presents diagnostics. Its command contract describes the implemented interface. Its Go entry point is main.go, with private application utilities under internal/. The module is github.com/anpep/axis.

Distribution wiring connects the subsystems: the shipped construction definitions include the runtime executable, and the application supplies the filesystem policy needed for Base OS conformance. These choices belong to the application, not to a general-purpose construction API. Examples describe the supplied application project.

Specification rules

MUST and MUST NOT express requirements. SHOULD expresses a recommendation requiring a reason to depart from it. MAY permits behavior. A stated requirement is not evidence that it has already been implemented; each owner identifies its implemented limits.

Each specification defines its own concept and introduces its immediate children. Detailed definitions live at their owner. A document must not require a reader to follow a sibling or ancestor definition to understand its contract. Relationships between siblings belong to their nearest common parent. Source API references may identify concrete parameter types without importing another specification’s definition.

Reading proceeds from this overview into one subsystem, then into that subsystem’s concepts. No layer repeats a descendant’s full definition or skips ahead to its internal details. Code and documentation follow the same ownership tree; public APIs may connect sibling packages.

style.css is the importable Markdown stylesheet. Design rules record the corresponding implementation conventions.

Documentation publication describes the Cloudflare Pages workflow and the required access controls for axis.pub.