Documentation
Architecture FAQ
Design decisions and rationale behind LevitateOS components. Each answer explains why we chose a particular approach over alternatives.
Core Philosophy
What is LevitateOS and why does it exist?
LevitateOS is an independent operating system for daily use, competing directly with Arch Linux. It borrows Arch's philosophy (you maintain your own packages on a minimal base). Its userland (glibc, systemd, coreutils, OpenSSH and the rest of a minimal base) is built from Fedora 45 RPM packages instead of being compiled, and it keeps two root filesystems, A and B: the booted one is locked and changes are made in the other.
| Dimension | Arch Linux | LevitateOS |
|---|---|---|
| Target User | Power users seeking control | Same |
| Philosophy | Minimal base, user builds | Same |
| Package Manager | pacman + AUR | recipe (Rhai scripts) |
| Binary Source | Compiled from source | Userland built from signed Fedora 45 RPM packages |
| System changes | In place | Written into the other root, then booted |
| Build Time | Hours (compiling) | Minutes (extracting) |
Its sibling AcornOS is also an independent operating system, built by the same pipeline on musl, OpenRC and busybox, with its userland built from Alpine 3.24 APK packages. See Variants.
Why not just use Arch?
Arch requires compiling AUR packages. That means build dependencies, compiler toolchains, and waiting. LevitateOS builds its userland from signed Fedora RPM packages in minutes. Same philosophy, less waiting.
If you want to compile everything yourself, use Arch. If you want the same control without the compilation overhead, use LevitateOS.
Why not Fedora?
Fedora is a distribution of its own, GNOME-focused and opinionated. LevitateOS is a separate operating system: it uses Fedora's packages as parts, not its installer, package manager, kernel or update channels, and you build what you want on top of a minimal system.
Fedora ships a complete desktop experience. LevitateOS ships a minimal system with Recipe. Different goals, different users.
What is LevitateOS NOT?
- An embedded OS (too small, missing capabilities)
- A container base image
- A server-only distro
- A resource-constrained system
LevitateOS targets modern desktop and workstation hardware with full capabilities.
What are the system requirements?
| Component | Baseline |
|---|---|
| CPU | x86-64 (any 64-bit Intel or AMD processor) |
| RAM | 4 GB (8 GB with the desktop) |
| Storage | 64 GB, on NVMe, SATA, virtio, USB or SD/MMC |
| Firmware | UEFI, with Secure Boot disabled (the boot files are unsigned) |
Is this just a hobby project?
Boot the ISO. Run the scenarios. Read the commit history. Code speaks.
The scenarios boot the live ISO, install it, reboot into the installed system, log in and check it at runtime, and boot the other A/B root, all in VMs. If something doesn't work, open an issue with specifics.
distro-builder (ISO Builder)
Why build the userland from Fedora packages instead of from source?
- Current, maintained packages: one Fedora 45 release, locked to exact package versions
- glibc-based (not musl) for maximum compatibility
- No compilation required - binaries are pre-built
- Builds in minutes instead of hours
- Direct RPM extraction: the system recipe unpacks a locked set of packages into the root filesystem itself, recording each file's owner and mode without root. No package manager is involved
Fedora keeps the toolchain and libraries current, which matters for a desktop where users build new software, and the two A/B roots keep the previous working root bootable. Fedora is our parts supplier and nothing more: the installer, the rec* tools, A/B booting and Recipe are our own.
How do I know the RPMs are safe?
They're Fedora's own signed builds. cargo xtask base lock picks each package from Fedora's release and updates repositories and checks it against the repository checksum and the release's signing key before it is locked; builds then verify every RPM against the locked SHA256.
We don't recompile packages. We don't inject code. We don't modify binaries. We extract what Fedora ships.
Why use EROFS instead of a large initramfs?
Loading the whole system into RAM as one large initramfs wastes memory and duplicates the system. The EROFS architecture provides:
- RAM savings: the system is read from the medium, not unpacked into memory
- Single source of truth: Live environment = Installed system (no duplication)
- Simpler installation:
recstrapextracts the same image to disk - Scalable: Easy to add packages without bloating initramfs
The live initramfs, built by recinit, contains just busybox, the boot modules and mount logic. It mounts the EROFS system image read-only, with the live overlay image and a tmpfs on top, and switches into it.
How does LevitateOS boot?
- systemd-boot everywhere - no GRUB or isolinux
- Live ISO: Unified Kernel Images built by
reciso, each one PE binary holding the kernel, initramfs and command line, which systemd-boot finds on its own - Installed system: one boot entry per root, A and B, each naming its own kernel and initramfs. The boot default is the root that last finished starting
Why UEFI-only (no BIOS support)?
LevitateOS targets modern hardware (2013+). UEFI has been standard for over a decade. Dropping BIOS support allows:
- Clean boot stack - systemd-boot only, no GRUB or isolinux complexity
- A/B boot selection - recab starts the other root once through systemd-boot
- Simpler code - One boot path to test and maintain
If you have hardware from before 2013 that lacks UEFI, LevitateOS is not the right distribution for you.
How are boot modules loaded?
recinit reads the kernel's modules.dep when it builds the initramfs and stores the boot modules in dependency order, so the init simply loads them in that order:
# Before (fragile - hand-maintained order)
load_module mbcache
load_module jbd2 # Must come after mbcache
load_module ext4 # Must come after jbd2
# After (resolved at build time against the exact kernel)
recinit build-tiny --modules-dir /lib/modules/6.12.0 ... # ext4 brings mbcache and jbd2, in order Benefits: No manual ordering, kernel updates won't break boot, easy to add new modules.
Why readelf instead of ldd for library detection?
ldd executes binaries with the host dynamic linker - broken for cross-compilation:
// Before (broken for cross-compilation)
let ldd_output = Command::new("ldd").arg(&bin_path).output();
// If host is musl and target is glibc → wrong libraries
// After (works everywhere)
let libs = get_all_dependencies(&ctx.rootfs, &bin_path)?;
// Reads ELF headers directly - no execution readelf reads ELF NEEDED entries directly from the file. No execution, no dynamic linker involvement. Works for any architecture on any host.
recipe (Package Manager)
Why Rhai instead of Python, Lua, or YAML?
YAML isn't a programming language - you can't write conditionals or loops. Python has dependency hell and isn't embeddable without significant overhead. Lua lacks a standard library. Rhai is Rust-native, sandboxed, and actually programmable.
This complete offline recipe copies an explicitly supplied script. Save it as copy-program.rhai, supply your script file, and run recipe install ./copy-program.rhai --input script=./script.sh --no-activate. The returned program path is the validated publication.
const RECIPE_API = 1;
const NEEDS = #{ inputs: #{ script: "file" }, outputs: #{ program: "file" } };
const PACKAGE = #{ name: "copy-program", description: "Copies a supplied script" };
fn build(src, out) {
copy_file(INPUTS.script, out);
chmod(out, 0o755);
} - Facts as data - Sources, files and packages are literal declarations; code is for what is unusual
- Infinite extensibility - Recipes define logic, not just data
- Minimal implementation - Recipe downloads, unpacks, places files, records what is done, installs and removes; the recipe supplies build() only when it has something to build
- Isolated - A recipe that starts programs runs inside an isolated Ginux domain. A recipe that starts none runs on the host, confined by Recipe to its own folders and declared network hosts
Where does recipe keep its state?
Recipe files are never rewritten. Recipe decides what state a program is in (none, downloaded, built or installed) from its own records, not by running recipe code: a download by its SHA-256 in the download store, a result by its identity and recorded file checksums, an installed program by its receipt. A recipe that must remember a value across an interruption uses save and checkpoint; the checkpoint lives under the state directory (~/.local/state/recipe by default), one at most, and is deleted when the install succeeds.
- Package facts come from the recipe - name, version and digests are read fresh on every run
- Outputs are published - a successful run returns the published paths in
outputs - Material is temporary - after a successful install the downloads, unpacked sources, build material and saved state are deleted unless
--keepwas given
What is the recipe lifecycle?
recipe install foo
├── download fetch SOURCES and pins into the download store
├── build unpack, place FILES, run build() or configure(), verify()
├── install activate the package, write the system tree, or publish outputs
└── cleanup delete downloads, unpacked sources, build material, saved state install runs every step still missing, in order, then cleanup unless the user chose to keep the material. Each step can also be run alone with recipe download, build and cleanup. See Recipe Format.
How does recipe handle dependencies?
- Literal declarations:
let deps = [...]andlet build_deps = [...], read before launch without running the recipe - Dependency order: dependencies install first, each running under its own NEEDS
- Shared tools: a dependency's output reaches the recipe through
DEPS, and atoolsoutput is put onPATH - Inheritance:
//! extends: base.rhaireuses one base recipe - Verified sources: downloads need a SHA256, Git checkouts a full commit id
Are recipes trusted code? What about security?
Yes, recipes are trusted code. They can run commands, download files, and install software. This is intentional.
A recipe that starts programs runs inside a Ginux domain with bounded memory, storage and time, network limited to declared NEEDS endpoints that callers may only narrow, and no view of the host's files beyond the inputs they are given. A recipe that starts no program runs on the host, confined by Recipe to its own folders and declared network hosts. The Recipe page explains both. On an A/B installation the booted root is locked, so Recipe writes system changes into the other, unlocked root. If the other root does not finish starting, the machine starts the previous root again.
- Recipes are code whose effects remain bounded by the supported configured contract
- Only use recipes from official LevitateOS sources
- You write your own recipes - you control what they do
- Never run recipes downloaded from untrusted sources
This is the same trust model as Arch's PKGBUILD or Gentoo's ebuilds. The user is responsible for reviewing what they install. Isolation and the two A/B roots limit the damage, but they don't make untrusted recipes safe.
Testing Philosophy
Why end-to-end (E2E) testing instead of unit tests?
LevitateOS tests the real artifacts with named scenarios. Each one runs on its own against existing build outputs:
| Scenario | Checks |
|---|---|
| build-preflight | The build inputs and host prerequisites |
| test-live-ssh | The test ISO boots to the live system and takes an SSH login |
| test-install-base | The install tools work in the test installer |
| install | Partition, extract, configure and install the bootloader on a VM disk |
| test-installed-boot | The installed disk boots |
| automated-login | Login on the installed system |
| runtime | The installed system's services and behavior at runtime |
| ab-update | Boot the other root and check that the roles swap |
Unit tests can't catch system integration issues. Installation is inherently end-to-end. The scenarios run in libvirt VMs with UEFI firmware, a virtual disk and a serial console.
Lessons Learned
What happened with the bootstrap tarball approach?
A costly mistake. The original plan:
ISO builder → bootstrap.tar.xz (~5MB) → Extract → recipe install base → Updates What was built: 34 recipe files, bootstrap module, busybox download, static binary compilation - all unnecessary.
The simple solution: The live ISO already contains a complete system in an EROFS image. Just extract it:
Boot ISO → recpart apply (mounts /mnt) → recstrap /mnt (extracts EROFS) → Done Lesson: Always ask "is this necessary?" before building. The simplest solution is usually correct.
How does LevitateOS stay aligned with Arch's approach?
When unsure about UX decisions, ask "What does archiso do?"
- Autologin: archiso has autologin → LevitateOS has autologin
- Root shell: archiso boots to root shell → LevitateOS boots to a root shell beside the install guide
- Installer: archiso requires manual install → LevitateOS uses recpart, recstrap (like pacstrap), recfstab (like genfstab) and recsetup, with a TUI for each step
LevitateOS competes with Arch. The live ISO experience should match archiso's behavior where applicable.
Technical Decisions Summary
| Decision | Alternative | Why Chosen |
|---|---|---|
| Userland from Fedora packages | Compile from source | Minutes vs hours, maintained packages |
| A/B roots | Change in place | The booted root is locked; changes go into the other root |
| EROFS | Large initramfs | RAM savings, scalability, single source |
| Rhai recipes | S-expressions/YAML | Real programming, infinite extensibility |
| Ginux domains for recipes that start programs | Run everything on the host | Isolation, explicit inputs, no network by default |
| E2E scenarios | Unit tests | Catches integration issues |
| Build-time module order | Hand-ordered insmod | No manual ordering, robust |
| readelf | ldd | Cross-compilation safe |