PyrixOS

A Reproducible Declarative Linux Distribution Configured in Hermetic Python

PyBonsai system descriptions, the Lattice package manager and the Cloche sandbox

PyrixOS is under development. Its source repository is public on GitHub. Current status: Phases 1 to 8 complete and Phases 9 to 12 implemented on main; PyrixOS 0.2.0-alpha.1 and 0.1.0 pre-release images for x86_64, riscv64 and aarch64 are published on GitHub Releases and seven pure-Python packages are published on PyPI. Research and availability status.

Documentation Python packages GitHub ↗

A declarative Linux distribution configured in hermetic Python

PyrixOS is a reproducible, declarative Linux distribution. The entire operating system, from a single library to a bootable machine with its kernel, initial RAM disk, file systems, users, systemd services and boot loader entries, is described in PyBonsai, a hermetic subset of Python 3.12, and built by the Lattice package manager. Evaluating the same description always yields the exact same content-addressed derivation graph, every build runs inside an isolated sandbox with no network access, and nothing is ever modified in place.

Declarative distributions such as NixOS and Guix System established the immutable-store model, yet each requires learning a custom domain-specific language. PyrixOS keeps standard Python syntax while interpreting the abstract syntax tree directly without Python builtins, imports, I/O, mutation, unbounded loops or recursion. Because the six core components are written in pure Python with zero Rust or C extensions, the entire system bootstraps from source without a Rust toolchain in its base dependency closure.

Language & Configuration

PyBonsai & Trellis Kconfig

System and package descriptions are written in .pyb files evaluated in linear time with fuel and recursion guards. Target architecture (x86_64, riscv64, aarch64) and build options are selected in a menuconfig-style console backed by the Trellis CDCL SAT solver, which proves option consistency, explains conflicts with minimal unsatisfiable cores, and emits a verified config.pyb.

Hermetic Build Sandbox

Cloche Namespaces, OCI & microVMs

Every derivation builds inside Cloche using fresh unprivileged Linux user, mount, network, PID, UTS and IPC namespaces created directly via unshare(2), guarded by a synthesized BPF seccomp filter and cgroup resource limits. Only declared inputs are bind-mounted read-only; the network namespace has only a loopback interface. Stronger isolation backends run the same derivation inside an OCI runtime or a Firecracker, Cloud Hypervisor or OpenVMM microVM.

Store, Profiles & Binary Caches

Immutable Store & Atomic Generations

Outputs are published atomically to /lattice/store/<hash>-<name>, made read-only, and tracked in an SQLite dependency graph with mark-and-sweep garbage collection. lattice switch activates a new machine generation atomically and registers a systemd-boot entry for instant rollback. Prebuilt paths are substituted from Ed25519-signed HTTP and CernVM-FS caches with SLSA build provenance.

Architecture & core components

Every capability of PyrixOS is exposed identically through three interfaces: in-process via the lattice.Lattice Python class, over the local Unix domain socket /run/lattice/daemon.sock via lattice.Client and lattice daemon on multi-user systems, and remotely over mutually authenticated TLS 1.3 via JSON-RPC 2.0 and REST.

Component PyPI package Role in the distribution
PyBonsai pybonsai-lang 1.2.1 Deterministic, total configuration language. Parses Python 3.12 syntax via ast.parse and evaluates an allow-listed AST with no builtins, imports, while loops, mutation, recursion or dunder attribute access.
Lattice pyrixos-lattice 0.14.0 Package and system manager. Evaluates PyBonsai descriptions into SHA-256 content-addressed derivations, schedules parallel builds, manages /lattice/store and its SQLite reference graph, switches machine generations and serves binary caches.
Cloche cloche 1.2.1 Rootless Linux sandbox. Isolates builds in unprivileged user, mount, PID, network, IPC and UTS namespaces with pivot_root(2), PR_SET_NO_NEW_PRIVS, per-architecture BPF seccomp filters (x86_64, aarch64, riscv64) and deterministic environments.
Trellis trellis-kconfig 1.1.1 Kconfig configuration engine with a pure-Python CDCL SAT solver (plus optional PicoSAT backend). Encodes option trees into CNF clauses, computes minimal conflict explanations and minimal correction sets, and writes config.pyb.
Espalier pyrixos-espalier 1.1.1 Pure-Python schema validation and immutable data modelling library implementing the BaseModel, ConfigDict, Field and TypeAdapter interface with JSON, YAML 1.2 and XML serialization and no compiled C or Rust extensions.
pyrixos-ed25519 pyrixos-ed25519 1.0.1 Pure-Python RFC 8032 Ed25519 signing and verification used by Lattice to sign and verify store-path cache manifests and SLSA v1.0 provenance attestations.
Coldframe coldframe 0.1.0 Project scaffolding and quality-gate runner (format, lint, typecheck, test with coverage floor, and audit) configured in pyproject.toml and used across all PyrixOS component repositories locally and in CI.

Eight-layer package set & fixed-point bootstrap

A PyrixOS system is built from an ordered eight-layer package set in pkgs/ (specified in RFC 0002 and RFC 0005). Starting from a single 24 MB binary seed verified by SHA-256, Stages 1 to 3 build a clean C toolchain, C library and core userland in the Cloche sandbox so that Stage 3 contains zero references to the bootstrap seed. Rebuilding the seed from Stage 3 produces seed-1, which is a byte-for-byte fixed point.

Layer file Stage / scope What it builds
pkgs/00-bootstrap.pyb Three-stage bootstrap & fixed-point seed Builds Stages 1, 2 and 3 from the binary seed (binutils, GCC, Linux API headers, glibc, bash, coreutils, make, sed, gawk, grep, diffutils, findutils, tar, gzip, xz) and verifies that rebuilding the seed from Stage 3 reproduces seed-1 bit-for-bit.
pkgs/10-stdenv.pyb Standard build environment Defines the hermetic stdenv builder, target triples and cross-compilation wrappers read from Trellis config["ARCH"] for x86_64, riscv64 and aarch64.
pkgs/20-base.pyb Base libraries & user space zlib, zstd, bzip2, lz4, openssl, libffi, expat, sqlite, ncurses, readline, attr, acl, libcap, libseccomp, util-linux, e2fsprogs, dosfstools, kmod, iproute2, openssh, curl, git, nano and core system utilities.
pkgs/30-toolchains.pyb Build systems & cross toolchains pkg-config, autoconf, automake, libtool, m4, bison, flex, ninja, meson, cmake, qemu-user-static for cross-target stage execution, and optional LLVM / Rust toolchains when CONFIG_RUST=y.
pkgs/40-system.pyb Kernel, initramfs & service manager Linux kernel with architecture defconfigs and configuration fragments, initial RAM disk (initrd) able to mount ext4, ISO 9660 + SquashFS overlay or PXE root.cpio, dbus, tzdata, locales and systemd with systemd-boot.
pkgs/50-python.pyb Python 3.12 & PyrixOS control plane CPython 3.12 and the six pure-Python PyrixOS packages (espalier, pyrixos_ed25519, pybonsai, cloche, trellis, lattice) packaged into the running distribution.
pkgs/90-images.pyb Disk, live ISO, netboot & VM builders Hermetic builders for GPT/EFI + ext4 raw disk images (disk_image), hybrid UEFI/BIOS SquashFS live ISOs, iPXE netboot trees, qcow2, VHDX, VDI, WSL rootfs tarballs, and U-Boot + OpenSBI board firmware.
pkgs/95-systems.pyb Machine definitions & installer Defines pyrixos_system, default_system, and the pyrixos-install utility that partitions a target disk, copies the store closure and SQLite registration offline, sets the root password and installs the boot loader.

Whole-machine descriptions, images & multi-architecture boot

In PyrixOS (RFC 0004 and RFC 0006), a complete machine is a PyBonsai value returned by machine(...). It declares the kernel, initial RAM disk, system packages, file systems, users and groups, /etc files, stack slots and systemd units. Building the description produces a single top-level store path; running lattice switch activates it atomically and adds a boot menu entry so any prior generation can be selected at boot.

Declarative system & image definition

# pkgs/systems/default.pyb
system = pyrixos_system(
    "default",
    default_file_systems(),
    services=[serial_autologin],
)

# Reproducible GPT (ESP + ext4) disk image built in the sandbox
image = disk_image(system)

# Convert to qcow2 (QEMU/KVM), VHDX (Hyper-V) and VDI (VirtualBox)
vm = vm_disks(image)

Build, boot & install across architectures

# Build and boot the default x86_64 disk image in QEMU (OVMF UEFI)
lattice build --package-set pkgs pkgs/systems/default.pyb image
scripts/boot-test.sh /lattice/store/...-pyrixos-image-1/pyrixos.img

# Build the hybrid UEFI/BIOS Live ISO or PXE netboot tree
lattice build --package-set pkgs pkgs/systems/live.pyb image
lattice build --package-set pkgs pkgs/systems/live.pyb netboot

# Build and boot RISC-V 64 or ARM64 images (UEFI or U-Boot + OpenSBI)
lattice build --package-set pkgs pkgs/systems/riscv64/default.pyb image
ARCH=riscv64 scripts/boot-test.sh /lattice/store/...-pyrixos-image-1/pyrixos.img
Target / artifact Description & entry point Boot loader & verification
Raw Disk Image (pyrixos.img) pkgs/systems/default.pyb (image) GPT disk with FAT32 EFI System Partition and ext4 root filesystem containing /lattice/store and generation 1. Boots via systemd-boot into systemd multi-user.target.
Installer Image (pyrixos-inst.img) pkgs/systems/installer.pyb (image) Boots to an installer environment providing pyrixos-install DISK; verified end-to-end by scripts/install-test.sh onto a second disk.
Hybrid Live ISO (pyrixos-live.iso) pkgs/systems/live.pyb (image) SquashFS root with tmpfs overlay and pyrixos-install; boots from DVD or USB via UEFI (systemd-boot) and x86_64 BIOS (GRUB).
PXE Network Boot (netboot) pkgs/systems/live.pyb (netboot) TFTP/DHCP directory containing ipxe.efi, boot.ipxe, kernel, initrd and root.cpio; tested against QEMU TFTP.
Virtual Machine Disks (qcow2, vhdx, vdi) pkgs/systems/default.pyb (vm) Native virtual disks for QEMU/libvirt (pyrixos.qcow2), Hyper-V Gen 2 (pyrixos.vhdx) and VirtualBox EFI (pyrixos.vdi).
WSL Root Filesystem (pyrixos-wsl.tar.gz) pkgs/systems/wsl.pyb (image) Windows Subsystem for Linux distribution archive with /etc/wsl.conf configured to start systemd; imported with wsl --import.
RISC-V 64 & ARM64 Systems pkgs/systems/riscv64/ & pkgs/systems/aarch64/ Full Stage 1 to 3 bootstrap and system images for riscv64 and aarch64, booting via UEFI (systemd-boot) or U-Boot with OpenSBI (FIRMWARE=u-boot).

Implementation status & RFC specifications

PyrixOS is developed in fourteen phases defined in the development plan, with every subsystem specified in an RFC before implementation. Phases 0 to 8 are complete and published on PyPI, and the bootstrap, whole-machine configuration, layered package set, installer, multi-architecture image builders and signed binary cache pipeline (building guide) of Phases 9 to 12 are implemented on main with PyrixOS 0.2.0-alpha.1 pre-release images published on GitHub Releases.

Phases Specification Deliverables & verification status
Phases 0 to 1
Architecture & PyBonsai Evaluator		 RFC 0001 Implemented. Hermetic AST evaluator, SHA-256 derivation hashing, Lattice standard library, Lattice Python API, lattice daemon (Unix socket + TLS 1.3 JSON-RPC 2.0 and REST) and lattice eval.
Phases 2 to 3
Cloche Sandbox, Store & GC		 RFC 0001 Implemented. Unprivileged namespace sandbox with BPF seccomp filters, immutable /lattice/store, SQLite dependency graph, parallel builder, lattice build --check reproducibility verification and garbage collector.
Phases 4 to 6
Profiles, Binary Caches & microVMs		 RFC 0001 Implemented. Atomic profile generations and rollback, stack slots, Ed25519-signed HTTP and CernVM-FS binary caches with SLSA provenance, shallow store paths, and OCI / Firecracker / Cloud Hypervisor / OpenVMM sandbox backends.
Phases 7 to 8
Trellis Kconfig & PyPI Releases		 RFC 0003 Complete. Kconfig parser, CDCL SAT solver, minimal conflict explanations, trellis menu console, and standalone releases of all seven packages on PyPI with PEP 740 trusted-publishing attestations.
Phase 9
Source Bootstrap & Fixed-Point Seed		 RFC 0002 Implemented on main. Stages 1 to 3 built in Cloche from the binary seed; Stage 3 rebuilds seed-1 bit-for-bit with zero references to the initial seed.
Phase 10
System Configuration & lattice switch		 RFC 0004 Implemented on main. Whole-machine machine(...) descriptions (including root_shell and /etc/profile.d/*.sh), atomic activation of /etc, users, mounts, slots and systemd units, per-generation systemd-boot entries and delegated cgroup build limits.
Phase 11
Package Set, Kernel & Installer		 RFC 0005 Implemented on main. Eight-layer pkgs/ set, Linux kernel, initramfs, systemd, Python 3.12, offline store closure registration, bootable disk image and pyrixos-install installer verified in QEMU.
Phase 12
Multi-Arch, Live ISO, Netboot & VM Images		 RFC 0006 Implemented on main. Cross and native builds for x86_64, riscv64 and aarch64; hybrid UEFI/BIOS live ISO, iPXE netboot, qcow2, VHDX, VDI, WSL rootfs and U-Boot + OpenSBI firmware published in the PyrixOS 0.2.0-alpha.1 pre-release.
Phase 13
PyrixOS 1.0 Release		 RFCs 0001 to 0006 In progress. Finalizing public binary cache keys, signed release images, long-term format stability guarantees and pyrixos-lattice 1.0.0.
Phase 14
AI and HPC Stack		 Roadmap §14 Planned. Reproducible packaging of the AI and HPC communication, accelerator and diagnostics stack (rdma-core, libfabric, PMIx, Open MPI, MVAPICH, UCX, gdrcopy, NCCL, RCCL, CUDA toolkit, DCGM, NVIDIA fabric manager and open kernel modules) selectable with Trellis Kconfig options and switchable via Lattice stack slots.

Curious?

Send a curiosity request and we will write back when there is something to say about PyrixOS.

Licence

PyrixOS is developed to be released under the GPL-2.0-only. Everything Packet Five Networks publishes is open source and free for anyone to use.

Keep an eye on the Research and availability status (subscribe to updates).

Documentation Python packages View on GitHub ↗ Availability status All research projects Get in touch