Docs: Architecture FAQ

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.

DimensionArch LinuxLevitateOS
Target UserPower users seeking controlSame
PhilosophyMinimal base, user buildsSame
Package Managerpacman + AURrecipe (Rhai scripts)
Binary SourceCompiled from sourceUserland built from signed Fedora 45 RPM packages
System changesIn placeWritten into the other root, then booted
Build TimeHours (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?

ComponentBaseline
CPUx86-64 (any 64-bit Intel or AMD processor)
RAM4 GB (8 GB with the desktop)
Storage64 GB, on NVMe, SATA, virtio, USB or SD/MMC
FirmwareUEFI, 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: recstrap extracts 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:

Shell
# 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:

Rust
// 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.

copy-program.rhai
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 --keep was given

What is the recipe lifecycle?

Text
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 = [...] and let 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 a tools output is put on PATH
  • Inheritance: //! extends: base.rhai reuses 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:

ScenarioChecks
build-preflightThe build inputs and host prerequisites
test-live-sshThe test ISO boots to the live system and takes an SSH login
test-install-baseThe install tools work in the test installer
installPartition, extract, configure and install the bootloader on a VM disk
test-installed-bootThe installed disk boots
automated-loginLogin on the installed system
runtimeThe installed system's services and behavior at runtime
ab-updateBoot 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:

Text
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:

Text
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

DecisionAlternativeWhy Chosen
Userland from Fedora packagesCompile from sourceMinutes vs hours, maintained packages
A/B rootsChange in placeThe booted root is locked; changes go into the other root
EROFSLarge initramfsRAM savings, scalability, single source
Rhai recipesS-expressions/YAMLReal programming, infinite extensibility
Ginux domains for recipes that start programsRun everything on the hostIsolation, explicit inputs, no network by default
E2E scenariosUnit testsCatches integration issues
Build-time module orderHand-ordered insmodNo manual ordering, robust
readelflddCross-compilation safe