Architecture
How Zainium OS is put together — the layers, how the system view is built at boot, and how libraries are found.
The layers
| Layer | Path | Contents | Changed by |
|---|---|---|---|
| Base | /overlayer/syshub | The complete OS: musl, toolchain, systemd, desktop, drivers | Base upgrades only, applied at boot |
| Userland | /overlayer/zexlib/union | Software installed with zex | zex install, remove, update |
| Boot | /overlayer/zaisys | Kernel, initramfs, boot loader (read-only) | Base upgrades, the installer |
| Agents | /overlayer/agents | Instructions and skills for AI coding agents | Admin |
The base never receives a file from the userland. If the userland is deleted, the base still boots on its own.
How the system view is built at boot
- Limine (UEFI or BIOS) loads the kernel
linux-zainiumandquantra-ramfs.img. - quantra-ramfs starts the Plymouth splash, waits for devices and mounts the root: the root partition on an installed system, or the read-only EROFS image
zaisys/zairoot.imgon the live ISO. - If a base upgrade is staged in
/overlayer/.syshub-pending, it is applied to/overlayer/syshubnow, before anything uses it, with a journal: a failed upgrade is undone, or the boot stops. A requested rollback undoes the last applied upgrade instead. Then every system file is checked to be sealed with fs-verity. - The system view is mounted with OverlayFS at
/overlayer/syshub, read-only andsealed: the base as the lower layer,zexlib/unionas the upper layer. Root cannot write to it or remount it writable, and a package zex installs intozexlib/unionappears in/overlayer/syshub/binat once. Itsetcandvarare writable layers of their own, kept inzexlib/union/etcandzexlib/union/var. zaisysgets its own read-only mount that root cannot remount writable;zexlibandagentsare mounted at their own paths;/homeand/rootcome from the disk. There is no/varat the root.- The root is switched and systemd starts. It runs greetd with cosmic-greeter, which starts the COSMIC desktop.
Live ISO and installed system
| Live ISO | Installed | |
|---|---|---|
| Root | zaisys/zairoot.img, read-only EROFS | disk partition |
| Installed software | in memory, lost at reboot | on disk |
/home, /root | in memory over the image | on disk |
| Base upgrades | not available | staged, applied at the next boot |
Programs and libraries
The base is built against musl with the x86_64-zainium-linux-musl toolchain. Every program records the musl loader /overlayer/syshub/x86_64-zainium-linux-musl/lib/ld-musl-x86_64.so.1 in its ELF header. The loader searches /overlayer/syshub/lib, the musl directory and /overlayer/zexlib/union/lib, in that order.
glibc is an optional package in its own directory; see musl and glibc. Software written for other distributions keeps working through path resolution.
How the OS is built
Zainium OS is built from scratch. Every package is built from source from a recipe (ZEXBUILD and manifest.toml): the base in syshub-recipes, community packages in userland-recipes. CI builds each recipe in a container against the Zainium musl toolchain, checks that every program uses the Zainium loader, signs the package and publishes it to archive.zainiumdynamics.tech. The ISO packs the root into a zstd-compressed EROFS image and boots with Limine on UEFI and BIOS.