LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.
LordOS on Raspberry Pi (ARM64)
Since M8, ARM64 is an official LordOS platform. The only supported board is the Raspberry Pi 5: it is the only one we test. Other boards may boot the same image, but they are not supported. This document gathers what's needed to build the image, write it, develop on the board and test it.
Status (2026-10-18): first bring-up on a real Raspberry Pi 5 (16 GB, SD card) running Raspberry Pi OS-style Debian 13 (kernel
6.18.50+rpt-rpi-2712, 16K pages, no monitor attached). Verified on the board: native build, the headless test suites, NEON, the arm64.deb, lord-sessiond and the login screen starting on vc4 without a monitor, andbuild-img.sh(see "Results on the board"). Not verified yet: anything with a monitor on HDMI (KMS modeset, GPU composition on screen, hardware cursor, FPS), the desktop session, remote-desktop screenshots, and booting the image thatbuild-img.shproduced.Update (2026-10-18, later): the image now ships the LordOS build of the Raspberry Pi kernel (
6.18.57-lordos-rpi-2712, Raspberry Pi's source andbcm2712_defconfigplus Landlock; see "The LordOS kernel"), switch files on the boot partition (ssh,remote-desktop, Wi-Fi inlordos-user.txt; see "Switch files") and a post-flash check (verify-board, see "After flashing"). Built on the board; it is verified by booting the reflashed card.Update (2026-10-19, 0.8.4):
build-kernel.shnow builds revision 3,6.18.57-lordos.3-rpi-2712(6.18.57-3+lordos): the same source and options plus sock_diagSOCK_DESTROY(INET_DIAG_DESTROY,INET_UDP_DIAG), so the firewall closes the connections a new rule denies instead of leaving them stalled. Each kernel revision now has its own release, so the previous one stays installed and bootable (see "Switching kernels on a board"). Cross-compiled on VM 116, installed on the Pi 5 and verified there:verify-board, the firewall cut test (15/15, TCP and QUIC closed in 0.04–0.37 s) andmake -C server test.Update (2026-10-25, 0.8.4.1): the Pi 5 image shows the login screen and the desktop on an HDMI monitor from the first boot (the display driver line in
config.txtnow comes afterdisplay_auto_detect/camera_auto_detect, plus 0.8.4's longer wait for the display driver;CHANGELOG.md, 0.8.4.1, Fixed). The image also brings Chromium, Firefox ESR and the ISO's system packages, and the bootloader is updated from Settings → Board firmware. A monitor plugged in after boot is followed since 0.8.5 (the login screen listens for the kernel's display events too). Frame rates with GPU composition on a 1920×1080 monitor were measured with LordBench's desktop test (BENCHMARK.md, "The desktop under load"). Still not measured: two monitors and 4K.Update (2026-10-27, 0.8.5): released with the image
lordos-0.8.5-rpi5-arm64.img.xz. A Pi 5 on 0.8.4 updated to the same package built as0.8.5~rc2withaptand restarted (no migration;CHANGELOG.md, 0.8.5, Upgrading). What changes on the Pi: the login screen follows a monitor plugged in after boot (SESSIONS.md), the Store follows apt's priorities so "Update all" no longer takes Raspberry Pi's builds of Debian packages, and packages with a+in their name (kms++-utils,libkms++0) download from lordos.org, so Settings → Board firmware can install the bootloader tools from the LordOS repository alone (PACKAGES.md). Still not measured: the same as above.
Models
| Board | Status | Notes |
|---|---|---|
| Raspberry Pi 5 (4, 8 or 16 GB) | supported (the only one) | BCM2712, 4× Cortex-A76 at 2.4 GHz, V3D 7.1 (OpenGL ES 3.1, Vulkan 1.3), kernel with 16K pages |
| Raspberry Pi 500 / CM5 | not supported | same SoC, so it may work; untested |
| Raspberry Pi 4 / 400 / CM4 | not supported | BCM2711; the image still carries a rpi-v8 kernel, but it is untested |
| Pi 3 and earlier, Zero 2 | no | too little RAM and an old vc4 GPU (GLES 2 without modern dmabuf) |
Recommended equipment
- Raspberry Pi 5 with 8 or 16 GB. It works with 4 GB, but GTK/Qt apps and Firefox take quite a lot.
- NVMe with the M.2 HAT+ (or any PCIe base for M.2 2230/2242). It's several times faster than an
SD card, and it shows when booting and opening apps. The image ships
dtparam=pciex1_gen=3; if the disk gives errors, comment that line out inconfig.txtand it stays at gen 2. - The official Active Cooler, or a heatsink with a fan. Without a fan, the Pi 5 throttles within a few minutes of load (video, compiling). The kernel drives the fan on its own.
- Official 27 W power supply (5 V, 5 A). With a 3 A one, the board limits USB to 600 mA and warns about it.
- HDMI monitor (micro-HDMI on the board) and a USB keyboard and mouse.
The image
tools/rpi/build-img.sh builds lordos-<version>-rpi5-arm64.img.xz. It is written the same way to an
SD card or an NVMe, and the same image boots on the Pi 5 and the Pi 4.
What it ships
Debian 13 (trixie) arm64, minbase, with the same LordOS packages as the ISO: PipeWire, wpa_supplicant, OpenVPN, Noto, foot, FeatherPad, automatic time (
systemd-timesyncd: the board has no clock that keeps time without a battery, and without it the clock started months behind, so every signed package index was refused as "not valid yet"), printing (cups,avahi-daemon), exFAT and NTFS drives, power profiles, the MIME database and the GSettings schemas (since 0.8.4.1).Chromium and Firefox ESR (Debian's arm64 builds, since 0.8.4.1), with the ISO's defaults from the same script,
tools/iso/browser-defaults.sh: Chromium'smaster_preferenceswithcustom_chrome_frameand the GTK theme, Firefox's/etc/firefox-esr/lordos.js(inTitlebar1), so both draw a single bar with LordOS's window buttons; the GTK themes, the video extension and the video settings (video-optimize, Settings → Displays → Video) come with the lordos package. Measured cost inISO.md, "Release test (0.8.4.1 Beta, October 25)".The LordOS build of the Raspberry Pi kernel (see "The LordOS kernel"), when
tools/rpi/build-kernel.shhas built it; otherwise Raspberry Pi's archive kernel, with a loud warning (it has no Landlock, BPF LSM or BTF):linux-image-<version>-lordos-rpi-2712: the Pi 5 one, with 16K pages (archive:linux-image-rpi-2712);linux-image-<version>-lordos-rpi-v8: the Pi 4/400/CM4 one, with 4K pages (archive:linux-image-rpi-v8). The Pi 5 can also use it, withkernel=kernel8.imginconfig.txt.
Firmware from the Raspberry Pi archive (
archive.raspberrypi.com/debian, suite trixie), only these packages (/etc/apt/preferences.d/raspberrypi):raspi-firmware: the boot files, device trees and overlays in/boot/firmware;firmware-brcm80211: Wi-Fi (CYW43455);rpi-eepromandraspi-utils(vcgencmd,pinctrl), if available.
Everything else comes from Debian, Mesa included. Since 0.8.4.1
rpi-eepromand what it needs are also in the LordOS repository (UPDATES.md, "Raspberry Pi firmware packages"): the same files, so either source updates the bootloader images; with both,apttakes the Raspberry Pi archive's copy (priority 990) and the result is the same.deb. Since 0.8.5 the Store's package engine follows/etc/apt/preferences.dlikeapt(PACKAGES.md, "How it resolves"); until then its "Update all" could take Raspberry Pi's builds of packages Debian also has (Chromium, BlueZ…).The bootloader (in the board's EEPROM) is updated from Settings → Board firmware (
SETTINGS.md, "Board firmware"), notraspi-config:rpi-eeprom-update's hint to runraspi-configdoesn't apply on LordOS.Bluetooth (the CYW43455's Bluetooth half, on a UART; see "Bluetooth"), from Debian:
bluez,bluez-firmware(the chip's patch,brcm/BCM4345C0.hcd),libspa-0.2-bluetooth(headsets in PipeWire) andrfkill, plus our SCO-routing helper (lordos-rpi-bt@hciN).Debian 13's Mesa: v3d (GLES 3.1), v3dv (Vulkan) and kmsro (vc4 for the display, v3d for rendering). lord-server is compiled with
GPU=1.The same LordOS package as the ISO. Built by
tools/iso/mkdeb.shwithDEB_ARCH=arm64.Partitions: MBR, in the layout Raspberry Pi Imager and the firmware expect:
Partition Size What it holds 1 bootfs512 MiB, FAT32 firmware, kernels ( kernel_2712.img,kernel8.img), initramfs, device trees,config.txt,cmdline.txt2 rootfsthe rest, ext4 the system; it grows on its own at first boot fstabandcmdline.txtuse PARTUUIDs, so the same image works for SD (mmcblk0) and NVMe (nvme0n1).
Kernel: why Raspberry Pi's and not Debian's
Researched as of October 2026 (confirm on the board):
Debian 13's kernel (
linux-image-arm64, 6.12 at release) boots on the Pi 4 with Debian'sraspi-firmware. On the Pi 5 it lacks full board support: the RP1 chip (USB, Ethernet, GPIO) and the BCM2712's display part reached Linux after 6.12, so without keyboard, network or HDMI it's no use.Also, Debian's
raspi-firmwareregeneratesconfig.txtandcmdline.txtwith every kernel, and would overwrite LordOS's configuration.The Raspberry Pi kernel (
linux-image-rpi-2712; 6.18 with its patches as of October 2026, it was 6.12 at trixie's release) is the one from Raspberry Pi OS Trixie. It has everything: RP1, vc4 with HDMI 4K60, v3d, the HEVC decoder, PCIe gen 3 and the fan.Its hooks copy the kernel to
/boot/firmwareunder the name the firmware looks for (kernel_2712.img). If they don't,build-img.shcopies it by hand. Chosen.
With the pinning, apt upgrade on the installed system keeps bringing the firmware from Raspberry
Pi, and everything else from Debian. The kernel is LordOS's own build of it (next section).
The LordOS kernel
Raspberry Pi's kernel leaves Landlock out (# CONFIG_SECURITY_LANDLOCK is not set, CONFIG_LSM="",
so /sys/kernel/security/lsm is just capability). LordOS confines apps (.lpk) and its helpers
(lord-doc, lord-media, lord-maild) with Landlock (server/src/sec/sandbox.c, see
PRIVACY.md); without it doc_evil.sh fails 5 of 25 and sandbox-test is skipped. It also has no
BPF LSM and no BTF (/sys/kernel/btf/vmlinux), which lord-netperm needs for "No Bluetooth" of
Linux apps (its per-cgroup LSM program on socket_create, FIREWALL.md); without them
npverify-test fails 35/36. The tests stay as they are: the fix is the kernel.
tools/rpi/build-kernel.sh builds it from Raspberry Pi's own source and defconfig, changing only
what LordOS needs:
# on the Pi (arm64 Debian 13): about 75 min per flavour on a Pi 5 (4 cores, SD card), ~10 GB free
sudo apt-get install -y --no-install-recommends build-essential bc bison flex libssl-dev libelf-dev \
libdw-dev dwarves cpio kmod rsync dpkg-dev debhelper git
tools/rpi/build-kernel.sh /var/tmp/lordos-kernel all # 2712 (Pi 5), v8 (Pi 4), or all
# → /var/tmp/lordos-kernel/out/linux-image-6.18.57-lordos.3-rpi-2712_6.18.57-3+lordos_arm64.deb, …
# or cross-compiled on an x86-64 Debian 13 (VM 116: 4 vCPU, 4 GB RAM; 67 min for 2712), the same
# packages plus the cross compiler and the arm64 libc headers (for the headers package's tools)
sudo apt-get install -y --no-install-recommends gcc-aarch64-linux-gnu libc6-dev-arm64-cross
RPI_KERNEL_REF=234188315037848e5b07d65b85d38edc64095caa tools/rpi/build-kernel.sh /var/tmp/pik-kernel 2712
The script cross-compiles by itself when the host isn't arm64 (CROSS_COMPILE=aarch64-linux-gnu-,
and DPKG_FLAGS=-d: dpkg-buildpackage would otherwise ask for arm64 build dependencies the kernel
doesn't use). The 0.8.4 packages were built that way: same commit, same .config (the diff
against the defconfig is identical to a native build's apart from the release name), same package
size as the native -2 (43 MB). With 4 GB of RAM a temporary 4 GB swap file was added for the
final link; the work folder peaked at about 16 GB. Don't build on the Pi in a tmpfs or with less
than 10 GB free on its SD card.
Source:
github.com/raspberrypi/linux, branchrpi-6.18.y(RPI_KERNEL_BRANCH;RPI_KERNEL_REF=<commit>pins one). The first build (2026-10-18) used commit234188315037, kernel 6.18.57; the archive shipped 6.18.50 at the time. The 0.8.1 rebuild (-2+lordos, BPF LSM and BTF) and the 0.8.4 one (-3+lordos, sock_diagSOCK_DESTROY) use the same commit.out/SOURCErecords it.Config:
bcm2712_defconfig(Pi 5, 16K pages) orbcm2711_defconfig(Pi 4, 4K pages), thenscripts/configandolddefconfig. The whole diff against the defconfig (out/config-*.diff):-CONFIG_LOCALVERSION="-v8-16k" +CONFIG_LOCALVERSION="-lordos.3-rpi-2712" -# CONFIG_SECURITY_LANDLOCK is not set +CONFIG_SECURITY_LANDLOCK=y -CONFIG_LSM="" +CONFIG_LSM="landlock,lockdown,yama,integrity,bpf" -# CONFIG_SECURITY_YAMA is not set +CONFIG_SECURITY_YAMA=y -# CONFIG_BPF_LSM is not set +CONFIG_BPF_LSM=y -CONFIG_DEBUG_INFO_NONE=y +CONFIG_DEBUG_INFO=y +CONFIG_DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT=y +CONFIG_DEBUG_INFO_BTF=y +CONFIG_DEBUG_INFO_BTF_MODULES=y -# CONFIG_INET_UDP_DIAG is not set +CONFIG_INET_UDP_DIAG=m -# CONFIG_INET_DIAG_DESTROY is not set +CONFIG_INET_DIAG_DESTROY=yplus what
olddefconfigderives from those (PAHOLE_HAS_SPLIT_BTF,PROBE_EVENTS_BTF_ARGS,FUNCTION_TRACE_ARGS, and a few new options answered "no").CONFIG_LSMuses the usual Debian order; the kernel skips the ones it doesn't build (lockdown and IMA/EVM stay off, as Raspberry Pi has them), so the active list iscapability,landlock,yama,bpf. The image'scmdline.txthas the samelsm=list.Yama (0.8.1), so the lordos package's
kernel.yama.ptrace_scope = 1(a process may only trace its own descendants) applies on the Pi as on a PC; with 0.8.0's kernel the sysctl had nothing to set.BPF LSM and BTF (0.8.1).
CONFIG_BPF_LSMletslord-netpermattach its per-cgroup LSM program (BPF_LSM_CGROUP) tosocket_create, so "No Bluetooth" is enforced for Linux apps on the Pi as on a PC; its attach point is the BTF id ofbpf_lsm_socket_create, read from/sys/kernel/btf/vmlinux(CONFIG_DEBUG_INFO_BTF, generated bypaholefrom the DWARF debug info: Debian'sdwarves). The debug info is only there to make BTF: the modules are stripped by the packaging (their.BTFsections stay) and the-dbgpackage isn't built (DEB_BUILD_PROFILES=pkg.linux-lordos-rpi-<flavour>.nokerneldbg), so the package hardly grows. The script checksvmlinuxhas a.BTFsection. The build needs about 10 GB free while it runs (the object files carry DWARF) and takes about 50 % longer.sock_diag
SOCK_DESTROY(0.8.4,-3+lordos). When a rule changes to deny,lord-netpermdrops the packets of the app's open connections and destroys its TCP and connected UDP (QUIC) sockets over sock_diag netlink, so the app sees the connection end (FIREWALL.md, "Existing connections are cut"). Destroying needsCONFIG_INET_DIAG_DESTROY(TCP) andCONFIG_INET_UDP_DIAG(UDP);INET_DIAGandINET_TCP_DIAGare already modules in the defconfig (enforced too), and the kernel loads them whenlord-netpermopens its sock_diag socket. Raspberry Pi's defconfig leaves the other two off. The options were inbuild-kernel.shsince 0.8.3, but the 0.8.3 image kept 0.8.2's-2+lordoskernel, so on the Pi the connections stalled until the app's own timeout (the journal saysthe kernel can't destroy TCP sockets). The script checksINET_DIAG_DESTROYstuck,build-img.shandverify-boardcheck the kernel config.Already in the defconfig, checked by the script so a future defconfig can't drop them:
SECCOMP_FILTER(sandbox.c), cgroup v2 withMEMCG,CGROUP_PIDSandCGROUP_SCHED(per-app limits;cgroup_enable=memoryis incmdline.txtbecause Raspberry Pi turns memcg off at boot), andBPF_SYSCALL,BPF_JIT,CGROUP_BPF(lord-netperm's cgroup hooks).USER_NSstays as Raspberry Pi has it, on (the launcher's own view for restricted Linux apps uses it).Packages:
make bindeb-pkg, version6.18.57-3+lordos(LORDOS_KREV;-1was 0.8.0's, without the BPF LSM,-20.8.1's, withoutSOCK_DESTROY), release6.18.57-lordos.3-rpi-2712(-lordos.3-rpi-v8for the Pi 4).- One release per revision (since
-3). Revisions 1 and 2 were both6.18.57-lordos-rpi-2712, so a new revision replaced the old one'svmlinuzand/lib/modulesin place: the old kernel couldn't stay bootable, since withMODVERSIONSandDEBUG_INFO_BTF_MODULES(withoutMODULE_ALLOW_BTF_MISMATCH) a kernel refuses another build's modules, Wi-Fi among them. Now-lordos.<rev>-rpi-<flavour>is its own package (linux-image-6.18.57-lordos.3-rpi-2712) next to the previous one, as Debian does with its ABI numbers. The.<rev>form is chosen for the order:sort -V(the hook's "newest") puts-lordos.3-after-lordos-, while-lordos3-or-3-lordos-would sort before it and the hook would keep copying the old kernel. - The
-rpi-<flavour>suffix is whatraspi-firmware's hook keys on, so it installs exactly like Raspberry Pi's:kernel_2712.img, initramfs, device trees and overlays in/boot/firmware. The script checks the package carries the device trees and overlays. Headers are built too (linux-headers-*), not put in the image. makegetsLOCALVERSION=(empty): otherwise, in a git tree that isn't at a tag, the release gets a trailing+(…-rpi-2712+) and the hook skips it as an unknown flavour.make dtbs_installdoesn't installoverlays/README, which the hook copies (and fails without): the script adds it to the package.- Measured on 2026-10-18 on the Pi 5 (load 4, 40–55 °C with the Active Cooler): 2712 in 50 min,
v8 in 49 min.
linux-image-6.18.57-lordos-rpi-2712_6.18.57-1+lordos_arm64.deb32 MB (vmlinuz 10 MB, 385 overlays) andlinux-image-6.18.57-lordos-rpi-v8_…33 MB;out/SHA256SUMSlists them. The v8 diff is the same three options (-v8→-lordos-rpi-v8).
- One release per revision (since
Not replaced by the archive.
build-img.shinstalls the LordOS.debsfromKERNEL_DEBS(default/var/tmp/lordos-kernel/out) instead oflinux-image-rpi-<flavour>, and writes/etc/apt/preferences.d/lordos-kernelwith priority -1 for Raspberry Pi's kernel packages of that flavour (linux-image-rpi-2712,linux-image-*+rpt-rpi-2712and the headers; checked withapt-cache policy: no candidate). Otherwise a newer+rptkernel would win the hook's "newestvmlinuz-*-rpi-2712" and boot without Landlock. Kernel updates come as new LordOS packages.Per flavour: if only the 2712 kernel was built, the Pi 4 kernel comes from the archive (with a warning, and without the pin).
Switching kernels on a board
The firmware reads config.txt on bootfs; os_prefix=<folder>/ makes it take the kernel,
initramfs, cmdline.txt, device trees and overlays from that folder instead of the top level. On
an installed system the top level is always what the packages put there: the newest LordOS kernel
(raspi-firmware's hook copies it on every install). The previous kernel stays installed (its own
/lib/modules) and its boot files go in a folder, lordos-prev/:
# keep the running kernel's boot files before installing a new one (once per revision)
K=$(uname -r); D=/boot/firmware/lordos-prev
sudo mkdir -p $D/overlays && sudo cp /boot/vmlinuz-$K $D/kernel_2712.img && sudo cp /boot/initrd.img-$K $D/initramfs_2712
sudo cp /boot/firmware/cmdline.txt $D/ && sudo cp /usr/lib/linux-image-$K/broadcom/bcm27*.dtb $D/
sudo cp /usr/lib/linux-image-$K/overlays/* $D/overlays/
sudo dpkg -i linux-image-6.18.57-lordos.3-rpi-2712_6.18.57-3+lordos_arm64.deb # the hook: top level = new
# first boot of the new kernel only once: tryboot.txt = config.txt without os_prefix
sudo reboot "0 tryboot" # if it doesn't come up, any reset boots config.txt again
Use the new kernel:
config.txtwithoutos_prefix(the image's default).Back to the previous kernel: add, at the end of
config.txt(it's on the FAT partition, so any computer with a card reader can edit it if the board doesn't boot):[all] os_prefix=lordos-prev/Removing those two lines boots the new kernel again. To try the previous one once without editing
config.txt, put that line intryboot.txt(a copy ofconfig.txt) andsudo reboot "0 tryboot"; the next reset is back on the top level.uname -rtells them apart:6.18.57-lordos.3-rpi-2712(0.8.4) or6.18.57-lordos-rpi-2712(0.8.1–0.8.3's-2+lordos).The Pi 5 used for development (2026-10-19) has exactly this: the top level is
-3,lordos-prev/is-2, andtryboot.txtbootslordos-prev/once. Both were booted and checked.
Packages to build it
On a Debian 13 (x86-64 or arm64):
sudo apt-get install -y --no-install-recommends debootstrap fdisk dosfstools e2fsprogs xz-utils curl gpg \
util-linux dpkg-dev
# only on an x86-64 host: aarch64 emulation for debootstrap, apt and compiling
sudo apt-get install -y --no-install-recommends qemu-user-static binfmt-support
Building it
# on the development machine: the themes (they are JS, the same on every architecture)
npm run build
# on the Debian where it's built (VM 116 or the Pi itself), from the repository root
sudo tools/rpi/build-img.sh /var/tmp/lordos-rpi # → /var/tmp/lordos-rpi/out/
Steps:
lord-server and lord-sessiond for aarch64.
- If
server/build/is already aarch64 (make -C serveron the Pi), it is used. - If not, a separate arm64 chroot is built (
buildroot/, reused) and it's compiled inside withGPU=1. - Then
build/canvas-testruns, which compares NEON with C. If they differ, the build stops.
- If
The package:
DEB_ARCH=arm64 tools/iso/mkdeb.sh.debootstrap arm64: native on an arm64 host. On x86-64 it's two stages, with qemu.
The Raspberry Pi archive. Its key's fingerprint is verified (
RPI_KEY_FPR). Then the packages and the.debare installed.Configuration: the same as the ISO (locales,
pingwithout root, lordos.service on tty1, PipeWire with linger, thelordos-greeteruser), plus:- the first boot (
lordos-rpi-firstboot.service); - waiting for vc4 (
lordos.service.d/rpi.conf).
root is locked.
- the first boot (
The image:
sfdisk(MBR), FAT32 and ext4. Then the system is copied andfstabandcmdline.txtare written with the PARTUUIDs.xz -T0 -6and the.sha256.
Variables:
| Variable | What for |
|---|---|
RPI_SSH=1 |
SSH server on from the start (for development); without it openssh-server ships off and the ssh switch file turns it on |
KERNEL_DEBS |
folder with the LordOS kernel packages (build-kernel.sh), /var/tmp/lordos-kernel/out by default |
IMG_EXTRA_MB |
free space in the image, 512 by default |
MIRROR, RPI_MIRROR |
Debian and Raspberry Pi mirrors |
RPI_KEY_FPR, RPI_KEY_NOCHECK=1 |
the Raspberry Pi key |
Before the first build: check the fingerprint of the Raspberry Pi archive key
(gpg --show-keys raspberrypi.gpg.key) against an official source. The one in the script
(CF8A1AF5…7FA3303E) was checked on 2026-10-18: it is the same fingerprint as the key in the signed
raspberrypi-archive-keyring package (2025.1+rpt1) installed on a Raspberry Pi OS board.
The loose raspberrypi.gpg.key at the archive root still carries its 2012 SHA-1 binding signatures,
and apt's sqv rejects them since 2026-02-01 ("SHA1 is not considered secure": InRelease is not signed). So build-img.sh takes the key from the archive's raspberrypi-archive-keyring package
(re-signed with SHA-512), found through the Packages index; trust still comes only from the
fingerprint check. RPI_KEY_URL=<url> uses another key file instead.
Estimate: on x86-64 with qemu, 30–60 minutes the first time. Natively on the Pi 5 it was run on 2026-10-18 from the SD card (see "Results on the board").
Writing it
LordOS Imager (recommended;
IMAGER.md): in LordOS (App Launcher → System) or as a small app for other computers. It downloads the latest release, checks its signature, writes and verifies the card, and prepares the first boot (computer name, language, user, Wi-Fi, SSH and remote desktop, appearance, cooling) inlordos-firstrun.txt(next section).Raspberry Pi Imager: "Choose OS" → "Use custom" → the
.img.xz, and then the card or the NVMe.- Skip Imager's OS customization (it's designed for Raspberry Pi OS; newer versions write
cloud-init files that LordOS doesn't read). If it leaves a
userconf.txton the boot partition, LordOS uses it (see below). - Instead, add the switch files and
lordos-user.txtto thebootfspartition (see "Switch files");out/FLASHING.txtnext to the image has the exact steps for macOS.
- Skip Imager's OS customization (it's designed for Raspberry Pi OS; newer versions write
cloud-init files that LordOS doesn't read). If it leaves a
dd (Linux and other Unix-like systems):
shasum -a 256 -c lordos-<version>-rpi5-arm64.img.xz.sha256 xz -dc lordos-<version>-rpi5-arm64.img.xz | sudo dd of=/dev/rdiskN bs=4m # Linux: of=/dev/sdX bs=4M conv=fsyncbalenaEtcher: opens the
.img.xzdirectly.NVMe:
- it can be written with a USB-NVMe adapter from another machine;
- or boot the Pi from an SD card with LordOS (or Raspberry Pi OS) and write it with
ddto/dev/nvme0n1.
To make the Pi 5 boot from NVMe first:
sudo rpi-eeprom-config --edit # BOOT_ORDER=0xf416 (NVMe, then SD, then USB)
First boot
lordos-rpi-firstboot.service runs before lord-sessiond (/usr/lib/lordos/rpi/firstboot) and does
two things.
The LordOS Imager's settings (0.8.4). If the
bootfspartition has alordos-firstrun.txt,/usr/lib/lordos/bin/lordos-firstrunchecks it with a strict parser and, only if all of it is valid, applies it once: computer name, language, time zone, keyboard, Wi-Fi country and network (the derived WPA2 key, never the password), the user (from a yescrypt or SHA-512 crypt hash), automatic login, SSH (keys only or with passwords), remote desktop (local network only), Bluetooth, appearance and cooling (fan profile, CPU governor, aconfig.txtblock for a mild overclock or a lower clock). The file is then overwritten and deleted. An invalid file applies nothing and the steps below run as before. Format and details:IMAGER.md, "The first-run file". Tested by applying it (--root) to the real 0.8.3 image on a virtual USB stick; not yet booted on a board.Grows partition 2 to the end of the card or disk (
sfdisk -N 2,partx -uand an onlineresize2fs).The user, like the installer's "User" step (
docs/ISO.md).- With
lordos-user.txton thebootfspartition: it's copied fromlordos-user.txt.example, which ships in the image. It has user, name,password_hash(orpassword), computer name, language, time zone and keyboard.- It's validated with
install.c's rules: the name, reserved names, the computer name, the zone and the keyboard. - The user is created: groups
sudo,audio,video,inputandrender, linger and the language's folders. - The file is overwritten with zeros and deleted.
- It boots to the login screen, like an installed system (empty
AUTOLOGIN=). - The
userconf.txtfrom Raspberry Pi OS / Imager (user:hash) also works.
- It's validated with
- Without the file: setup mode.
- It logs in on its own with the
lordosuser, without a password and with passwordless sudo, like the live ISO. - In Settings → Users you create your own account, as an administrator. On the next boot
firstbootsees there's an administrator, deleteslordosand its sudo and switches to the login screen. - In the meantime, don't turn on remote desktop and don't leave the board exposed on the network.
- It logs in on its own with the
- With
Switch files (next section), on every boot.
Pending: a "create user" step of our own on the login screen, so setup mode isn't needed (see ROADMAP, M8).
Switch files
Like Raspberry Pi OS's ssh file: files dropped on the bootfs partition (FAT, editable from any
computer) before booting. firstboot applies each one, logs it (journalctl -u lordos-rpi-firstboot) and deletes it (overwritten with zeros first, since they can hold a password).
A name with .txt (as some editors save it) works the same.
| File | Contents | What it does |
|---|---|---|
ssh |
empty | Turns the SSH server on (systemctl enable ssh, started right away) and keeps it on. The image ships openssh-server off; each board creates its own host keys. Logging in needs an account with a password: root is locked and the setup user has none |
remote-desktop |
empty, or port=5673 and/or allow=all|group |
Turns LordOS remote desktop on (https://<board IP>:5673, REMOTE.md), writing the same /etc/lordos/remote/config (enabled=1, port=, allow=) that Settings → Sharing's remote-enable/remote-config write; lord-sessiond reads it when lordos.service starts. It still asks for a user and password: while there's no account with a password (setup mode) the file is kept and applied on a later boot. port must be 1024–65535 (5673 by default); allow=group limits it to the lordos-remote group |
lordos-user.txt |
from lordos-user.txt.example |
The first-boot user (above), read only on the first boot. Optional Wi-Fi: wifi_ssid=, wifi_password= (8–128 characters; empty for an open network) and wifi_country= (two letters) |
userconf.txt |
user:hash |
Raspberry Pi OS / Imager's user file, first boot only |
Wi-Fi at first boot. The image's network stack is lord-netd (no NetworkManager, no
systemd-networkd): at boot it brings up every free physical interface with its own DHCP client, and
on Wi-Fi interfaces it starts wpa_supplicant and loads the saved networks. firstboot saves the
network from lordos-user.txt the same way Settings → Network does
(/etc/lordos/net/wifi/<SSID in hex>.json, and .key with mode 0600), before lord-netd starts, so
the board joins it on the first boot. wifi_country adds cfg80211.ieee80211_regdom=<XX> to
cmdline.txt (the 5 GHz channels of that country, from the second boot; until then the world
domain). lord-netd skips interfaces NetworkManager manages, which only matters on Raspberry Pi OS.
Options in cmdline.txt (a single line), as on the ISO:
| Option | What it does |
|---|---|
lordos.gpu=0 |
safe mode: everything on the CPU |
lordos.lang=es / pt |
first-boot language (English by default, like the ISO) |
video=HDMI-A-1:1920x1080@60 |
pins the mode, for example on a 4K monitor (on the CPU, 4K is heavy: see below) |
remove splash (or add nosplash) |
boots in text, without the boot splash |
Boot splash
From power-on to the login screen the board shows the LordOS crown with a progress bar (the same
Plymouth theme as the ISO, ISO.md, "Boot splash and boot menu"), with no rainbow square, no kernel
logo and no console text.

config.txt:disable_splash=1: the firmware's rainbow square is not drawn.cmdline.txt:console=serial0,115200 console=tty1 … quiet splash plymouth.ignore-serial-consoles logo.nologo vt.global_cursor_default=0 loglevel=3, keepingroot=,lsm=,cgroup_enable=memoryandlordos.lang=. The local console moved fromtty3totty1: Plymouth takes its terminal (keyboard, password prompt, Esc) from the localconsole=and LordOS runs on tty1, so both stay on the same VT (Raspberry Pi OS does the same). The kernel's messages stay hidden (quiet, Plymouth); Esc shows them during the boot, as usual.- initramfs:
plymouthandplymouth-labelare installed andlordosis the selected theme (plymouth-set-default-theme lordos), so Plymouth's initramfs hook copies the theme, its plugins and a font (for the encrypted-disk password prompt)./etc/initramfs-tools/moduleslistsvc4andconf.d/lordos-splash.confkeepsMODULES=most(the hook then adds the DRM drivers), so the HDMI output is up in the initramfs and the splash shows within the first seconds instead of after the root file system is mounted. The LordOS kernels haveDRM,DRM_VC4andDRM_V3Das modules, and their packages build an initramfs through/etc/kernel/postinst.d(initramfs-tools); the raspi-firmware hook andbuild-img.shcopy it asinitramfs_2712/initramfs8(auto_initramfs=1).build-img.shfails if an initramfs has nolordos.script. - Hand-off: the same as the ISO (
SESSIONS.md, "Boot splash"); on the Pilordos-splash deactivateruns afterwait-kms, so Plymouth keeps drawing until vc4 is ready. Plymouth draws on vc4 (card1), the card with the HDMI connectors;v3d(card0) has none. - First boot:
lordos-rpi-firstboot(growing the partition, the user, the switch files) runs under the splash; its messages go to the journal and to the console, which Plymouth keeps hidden (Esc shows them).
Checked on the image (read-only, loop-mounted on the Pi): config.txt, cmdline.txt, the default
theme and lsinitramfs of both initramfs files. Still to check on a board: the timing of the first
frame of the splash after power-on, the hand-off with no flash on vc4, and 4K.
Bluetooth
The Pi 5's Bluetooth is the second half of its CYW43455 (Wi-Fi is the first, on SDIO), wired to a
UART of the BCM2712. On the Pi 5 the kernel brings it up by itself, with no hciattach and none of
Raspberry Pi OS's pi-bluetooth scripts:
- The device tree (
bcm2712-rpi-5-b.dtb) has abrcm,bcm43438-btnode under the UART, so the serial-device bus bindshci_uartwith its BCM protocol (CONFIG_BT_HCIUART_SERDEV,CONFIG_BT_HCIUART_BCM, both in Raspberry Pi's defconfig and so in the LordOS kernel). It also carriesshutdown-gpios(power),max-speedandlocal-bd-address, which the board firmware fills in with the board's own address before the kernel starts. btbcmloads the chip's patch: it looks forbrcm/BCM4345C0.raspberrypi,5-model-b.hcdand thenbrcm/BCM4345C0.hcd. The image takes it from Debian'sbluez-firmware(non-free-firmware, the same 63,806-byte file as Raspberry Pi's+rptpackage, which only adds per-model symlinks), so the generic name is the one used. The chip reports the placeholder address43:45:c0:00:1f:ac; the kernel replaces it with the device tree's.- BlueZ (Debian's
bluez,bluetooth.serviceenabled) and the rest of the desktop side are the same as on a PC (SETTINGS.md, "Bluetooth"): our own D-Bus client inlord-server, the system-drawn pairing prompts, and headsets in PipeWire throughlibspa-0.2-bluetoothwith the lordos package's WirePlumber drop-in (lordos-bluez.conf). - SCO routing, our helper. Call audio (HFP/HSP: a headset's microphone) can leave the chip over
HCI or over its PCM pins, which the Pi doesn't wire. Raspberry Pi OS's
bthelpersets HCI with a vendor command of the chip; LordOS does the same with its own/usr/lib/lordos/rpi/bt-uart, run by[email protected](udev starts it for anhciNwhose parent is on the serial bus,/etc/udev/rules.d/90-lordos-rpi-bt.rules; beforebluetooth.service). It reads the setting back first (Read_SCO_PCM_Int_Param, 0xfc1d) and only writes (Write_SCO_PCM_Int_Param, 0xfc1c,01 02 00 01 01: routing over HCI, with the same other parameters asbthelper) when it differs, leaves the controller powered as it found it, skips a controller blocked by rfkill or not on a UART, warns if the address is still the chip's placeholder, and never fails the boot. It useshciconfig/hcitoolfrom Debian'sbluez;lord-serverstill never runs either (it speaks D-Bus tobluetoothdonly). The setting survives a power cycle of the controller from Settings (an HCI reset): checked on the board. - Not used from Raspberry Pi OS:
pi-bluetooth(hciuart.service/btuartare for the older boards'hciattachand exit at once when the kernel already drives the chip;bthelperis replaced by the helper above, without its "power off and on again after 5 s" workaround, which the kernel driver doesn't need: Secure Simple Pairing is on from the start).
To turn Bluetooth off for good, dtoverlay=disable-bt in config.txt (the UART is then free); the
switch in Settings → Bluetooth only powers the controller off.
Checked on a Pi 5 (2026-10-18, LordOS kernel 6.18.57-2+lordos): hci0 on the UART with the
board's own address (88:A2:…, not the chip's placeholder), bluetoothctl show powered, and a
12-second scan lists the devices around it (4 to 5 in that room). "No Bluetooth" for a Linux app:
in the app's scope socket(AF_BLUETOOTH) gets EPERM, outside it works (FIREWALL.md, "Bluetooth
sockets"). Not checked yet: pairing and a headset's audio on the board (they need a device in
pairing mode next to it), and Settings → Bluetooth on the board's own screen (no LordOS session was
open; it is the same page and the same D-Bus client as on a PC, SETTINGS.md).
The image built with this kernel (lordos-0.8.1-rpi5-arm64.img.xz, 2,717 MB uncompressed) was
checked read-only, loop-mounted: our kernel_2712.img on bootfs with BPF_LSM, BTF, Yama and
Landlock in its config, lsm= with bpf in cmdline.txt, bluez, bluez-firmware (with
brcm/BCM4345C0.hcd), libspa-0.2-bluetooth, rfkill, hciconfig/hcitool, the helper, its unit
and udev rule, lordos, lord-netperm, lord-fand and bluetooth enabled, SSH off. The Pi 4
kernel in it (-rpi-v8) is still 0.8.0's 6.18.57-1+lordos, without the BPF LSM: "No Bluetooth" is
only enforced on a Pi 4 once that flavour is rebuilt (build-kernel.sh … v8).
After flashing
tools/rpi/verify-board.sh (in the image as /usr/lib/lordos/rpi/verify-board) checks a freshly
booted board and prints a PASS/FAIL table. It only reads /sys, /proc, the kernel log and the
configs; it changes nothing.
sudo /usr/lib/lordos/rpi/verify-board # system checks
sudo /usr/lib/lordos/rpi/verify-board --repo ~/LordOS # plus make -C server test-full and doc_evil.sh
| Check | PASS when |
|---|---|
| kernel | uname -r is a -lordos-rpi-* or -lordos.<rev>-rpi-* kernel; page size 16K on the Pi 5 (4K with -rpi-v8) |
| socket destroy | the kernel config has INET_DIAG_DESTROY, INET_TCP_DIAG and INET_UDP_DIAG (the firewall closes the connections a new rule denies) |
| Landlock | /sys/kernel/security/lsm lists landlock; the kernel log says landlock: Up and running; the kernel config has SECURITY_LANDLOCK, SECCOMP_FILTER, CGROUP_BPF, BPF_SYSCALL, MEMCG |
| BPF LSM, BTF | bpf in /sys/kernel/security/lsm; /sys/kernel/btf/vmlinux present; the kernel config has BPF_LSM and DEBUG_INFO_BTF; lord-netperm active |
| seccomp, cgroups | seccomp available; the cgroup v2 memory controller is on (cgroup_enable=memory) |
| first boot | the root partition has grown; no switch file left on bootfs (WARN for a remote-desktop still waiting for an account); not in setup mode |
| display, GPU | a connected KMS output with its mode (WARN with no monitor); eglinfo -p gbm shows V3D; the session log shows GPU composition |
| fan, temperature | a fan hwmon (pwmfan, rpm and PWM; lord-fand active if it's installed); SoC < 75 °C; throttled=0x0 |
| Bluetooth | an hciN on the UART (with the patch file from the kernel log); bluetoothd active; lordos-rpi-bt@hciN active (WARN otherwise); the board's own address, not the chip's placeholder 43:45:c0:… |
| remote desktop | port 5673 (or the configured one) listens only when /etc/lordos/remote/config has enabled=1 |
| services | lordos.service active; SSH shown as on or off |
--repo |
make -C server test-full passes; doc_evil.sh N/N (25/25 with the archive tools installed); the three sandbox-test runs ok |
--repo needs the tree and the build packages ("Developing on the board"); it builds as the tree's
owner.
Display and GPU on the Pi 5
Two DRM devices
| Node | Driver | What it is |
|---|---|---|
/dev/dri/cardN (usually card1) |
vc4 |
the display: HVS, HDMI ×2, planes, cursor. It has no render node |
/dev/dri/cardM (usually card0) |
v3d |
the 3D GPU, without connectors |
/dev/dri/renderD128 |
v3d |
where Mesa renders |
The order of card0 and card1 depends on which driver loads first.
server/src/drmcard.h, new, is used by lord-server (main.c) and lord-sessiond (remote/monitor.c). It picks the first card that has connectors and CRTCs, and prefers the one with a monitor plugged in (GETRESOURCES+GETCONNECTOR).card0is no longer assumed. This also fixes PCs where simpledrm leaves the real card atcard1.LORD_CARD=/dev/dri/cardNpins it, and lord-server's--cardstill works.
lordos.service.d/rpi.confwaits up to 10 s for a connector to appear in/sys/class/drm(wait-kms, up to 30 s, and it asks forvc4withmodprobe; lord-sessiond then waits up to 30 s more for a card with KMS before showing the "no display" text). If lord-sessiond starts before vc4 is loaded, without this it would only see v3d.GBM and EGL are created on the display card (vc4), as always. Mesa recognizes it (kmsro) and renders with v3d. Scanout buffers are created on vc4 and v3d imports them. lord-server doesn't need to know anything about this.
The linux-dmabuf feedback announces the render node where Mesa renders:
gpu_device()ingpu/gpu.c. That way apps (GTK, Qt, games) ask v3d for their buffers and not vc4, which has no render node. It looks it up like this:- EGL (
EGL_EXT_device_query+EGL_EXT_device_drm_render_node); - the same card's render node;
- if the display card has none, the first render node there is (v3d).
The log says
gpu: GPU composition (V3D 7.1…, render /dev/dri/renderD128, display vc4).- EGL (
Modifiers
vc4's primary plane shows RGB only as linear. It also accepts
BROADCOM_VC4_T_TILED, which v3d doesn't render, andBROADCOM_SAND64/128/256only for YUV (NV12/P030, video). v3d renders in UIF (DRM_FORMAT_MOD_BROADCOM_UIF), which vc4 can't display.kms.c now reads the
IN_FORMATSproperty of the CRTC's primary plane (withDRM_CLIENT_CAP_UNIVERSAL_PLANES) and records the 32-bit RGB format/modifier pairs. The log says:kms: card vc4, XRGB8888 on the primary plane with modifiers: 0x0 …Direct scanout of a fullscreen app (
gpu_can_scanout) now requires the plane to accept the buffer's modifier (kms_scanout_ok). A v3d UIF buffer isn't sent to the display (before, ADDFB2 was tried and, if the driver accepted it anyway, garbage showed up).- The implicit modifier (
INVALID) counts as linear. - If the driver doesn't report
IN_FORMATS, everything stays as before.
- The implicit modifier (
The UI surface (
gbm_surface_createwithSCANOUT | RENDERING, without modifiers): with kmsro, Mesa creates it on vc4, linear. So it always displays.Apps' dmabufs are imported via EGL with their modifier. UIF is fine for textures: they're composited, they don't go to the display.
What to verify on the board
grep -E 'kms:|gpu:' ~/.cache/lordos/session.log(or the session log). It has to show:- the chosen card, with the
vc4driver; - the plane's modifiers (with
0x0, linear, present); GPU composition (V3D 7.1…);render /dev/dri/renderD128;cursor by hardware (cursor plane).
- the chosen card, with the
journalctl -u lordosshowslord-sessiond: display: /dev/dri/card1(or whichever).LORD_GPU_DEBUG=1:- the list of dmabuf formats EGL announces (it has to include UIF
0x0700000000000006and linear); - whether a fullscreen game goes through direct scanout or is composited.
- the list of dmabuf formats EGL announces (it has to include UIF
glmark2-es2-waylandandvkcubewindowed and fullscreen, with screenshots.- GTK4 (gtk4-demo) over dmabuf:
WAYLAND_DEBUG=1shows it requests v3d's render node;- the window looks right (no stripes from misinterpreted tiling).
- vc4's hardware cursor (
CURSOR2, 64×64). - Two monitors: today LordOS uses the first connected connector (HDMI-A-1); the second stays off.
- 4K monitor. On the CPU, the 3840×2160 canvas is 33 MB per buffer and copying it is costly. With
the GPU it should work well. If not,
video=HDMI-A-1:1920x1080@60.
Video (for the lord-media helper)
This part is for the media agent: it's what the Pi 5 needs besides VA-API, which is the PC path. Its files weren't touched.
The Pi 5 has no hardware H.264 decoder (the Pi 4 does, and it's no longer used). It only has hardware HEVC/H.265 (
rpi-hevc-dec), up to 4Kp60 at 8 and 10 bits.- It's a V4L2 stateless decoder ("request" API), at
/dev/video19and a/dev/mediaN. - There's no VA-API or VDPAU on the Pi.
- It's a V4L2 stateless decoder ("request" API), at
FFmpeg:
- Debian 13's (7.1) doesn't include the V4L2-request hwaccel; upstream doesn't have it yet.
- Raspberry Pi's (
archive.raspberrypi.com,+rptversions) does:-hwaccel drm, with thehevcdecoder anddrm_primeoutput. Some versions expose it ashevc_v4l2request.
Options:
- pin
ffmpegand the Raspberry Pilibav*at 990, like the kernel, only in the Pi image; - have
lord-mediaload an alternativelibavcodec; - speak V4L2-request directly from C (a lot of work).
Recommended: option 1. Add
ffmpeg libavcodec61 libavformat61 libavutil59 libswscale8 libswresample5 libavfilter10to/etc/apt/preferences.d/raspberrypi(verify the names withapt-cache policyon the board).Decoded frames are DRM PRIME:
- NV12 or P030 with the
BROADCOM_SAND128modifier: the Pi's "column" format; av_hwframe_map/AVDRMFrameDescriptorgive the fd, offset, pitch and modifier.
To display them:
- On the GPU (best): import them via EGL with the SAND128 modifier and
GL_OES_EGL_image_external. Mesa v3d has to accept SAND128 (it is believed to convert it with the TFU): verify withLORD_GPU_DEBUG=1. lord-server already imports multiplanar dmabufs with modifiers (gpu_tex_dmabuf) if the format is in the feedback. Todaygpu_formats()only announces 32-bit RGB (known[]ingpu.c): for video NV12/P030 have to be added. - Through a vc4 overlay plane: the HVS displays SAND128 directly (that's what Kodi does). LordOS doesn't use overlay planes yet (GPU.md, Pending).
- On the CPU:
av_hwframe_transfer_datato linear NV12 and convert. Good for 1080p; for 4K it's expensive.
- NV12 or P030 with the
H.264, VP9 and AV1 in software, on the 4 Cortex-A76 cores (FFmpeg and dav1d have NEON):
- H.264 1080p30/60 should work with 2–3 threads;
- 4K H.264 isn't realistic;
- AV1 1080p with dav1d, at the limit.
Use
thread_type = FF_THREAD_FRAME | FF_THREAD_SLICEandthreads = 4. With the Active Cooler, so it doesn't throttle.On the Pi 4: hardware H.264 (
h264_v4l2m2m, V4L2 stateful,/dev/video10, in Debian's FFmpeg) and HEVC viarpi-hevc-decas on the Pi 5.What the media agent has to measure on the board:
- CPU and dropped frames with 1080p H.264, 1080p HEVC and 4K HEVC;
- temperature (
vcgencmd measure_temp); - throttling (
vcgencmd get_throttled, it has to give0x0).
Developing on the board
There are two possible systems on the board:
- Raspberry Pi OS Lite 64-bit (Trixie): the kernel and firmware are already there, and Mesa comes from the Raspberry Pi archive. The simplest way to start.
- The LordOS image, built with
RPI_SSH=1.
Steps
SSH:
- with Raspberry Pi OS, enable it in Imager;
- with LordOS, put an empty
sshfile on the boot partition (or build withRPI_SSH=1) and use the account created at first boot; ssh user@<ip>; the IP shows up on the login screen or withip -4 addr.
Packages for compiling (the same as in
VM-SETUP.mdplus Mesa):sudo apt-get install -y --no-install-recommends build-essential pkg-config libxkbcommon-dev libwayland-dev \ wayland-protocols libgbm-dev libegl-dev libgles-dev libssl-dev libcrypt-dev libsrtp2-dev libusrsctp-dev xkb-data \ libgl1-mesa-dri libegl1 libgles2 libgbm1 mesa-utils glmark2-es2-waylandThe tree, from the development machine (as for the VM; the themes are built there):
npm run build COPYFILE_DISABLE=1 tar czf - --no-xattrs --exclude build --exclude node_modules \ package.json README.md server third_party assets themes tools | \ ssh user@<pi-ip> 'rm -rf ~/LordOS && mkdir ~/LordOS && cd ~/LordOS && tar xzf -'Compile on the board, natively, no cross-compiling:
cd ~/LordOS make -C server -j4 # ARCH=aarch64 is detected: NEON=1 and GPU=1 if the -dev packages are there make -C server test # all headless tests, including build/canvas-test server/build/canvas-test # NEON = C, and how long each one takesTest lord-server alone, from a console (Ctrl+Alt+F2, with lordos.service stopped):
cd ~/LordOS/server && sudo build/lord-server --user "$USER" 2> /tmp/lord.logInstall it on the LordOS image:
sh tools/iso/mkdeb.sh /tmp/lordos.deb(on the board it takesarm64fromdpkg --print-architecture) andsudo apt install /tmp/lordos.deb.Screenshots:
- LordOS's remote desktop (Settings → Sharing, port 5673;
REMOTE.md) from the development machine's browser, only on the LAN and turning it off afterward; - or
griminside a Wayland session.
There's no QEMU
screendump: it's a board.- LordOS's remote desktop (Settings → Sharing, port 5673;
Test checklist on the board
Each item, with a screenshot or the pasted output, in this document.
| # | Test | How | Expected |
|---|---|---|---|
| 1 | Boot | systemd-analyze, systemd-analyze blame | head |
SD: <25 s; NVMe: <12 s to the login screen |
| 2 | First boot | freshly written image, with and without lordos-user.txt |
partition grown (df -h /); login screen or setup mode; the file deleted |
| 3 | RAM | free -m, lord-server RSS (ps -o rss) |
idle desktop <400 MB total; lord-server ~35–60 MB (with 16K pages RSS goes up a bit) |
| 4 | Card and GPU | the log (see "What to verify") | vc4, V3D 7.1, renderD128, hardware cursor |
| 5 | GPU compositing FPS | glmark2-es2-wayland windowed and fullscreen; dragging windows; the app launcher |
60 FPS synced to vblank |
| 6 | CPU path | lordos.gpu=0 |
usable at 1080p; note ms per frame with --profile |
| 7 | Modifiers | LORD_GPU_DEBUG=1, kms: in the log |
linear on the plane; UIF only for textures; no garbage on screen |
| 8 | Apps' dmabuf | gtk4-demo, foot, FeatherPad (Qt6), vkcube |
they look right; WAYLAND_DEBUG shows renderD128 |
| 9 | 1080p video | H.264 and HEVC (once lord-media is there) |
no dropped frames; CPU noted |
| 10 | 4K video | hardware HEVC 4Kp60 | smooth; temperature noted |
| 11 | Temperature | vcgencmd measure_temp, vcgencmd get_throttled, LordOS Monitor (cpu_thermal and the fan) |
<75 °C with the Active Cooler under load; throttled=0x0 |
| 12 | NEON | server/build/canvas-test |
"NEON matches C"; NEON faster than C |
| 13 | Headless tests | make -C server test and each build/*-test |
all pass, as on x86 (WASM: the full wg-2.0 suite) |
| 14 | App isolation | open a .lpk; sandbox[...]: in the log; cat /sys/kernel/security/lsm; make -C server test-full |
capability,landlock; Landlock and seccomp=1; doc_evil.sh 25/25 and sandbox-test ok. Needs the LordOS kernel: Raspberry Pi's has no Landlock (6.18.50+rpt: seccomp only) |
| 15 | Remote desktop | Settings → Sharing, https://<ip>:5673 from the development machine |
visible and controllable; screenshots for this document |
| 16 | Network and sound | Wi-Fi (brcmfmac), Ethernet, HDMI audio via PipeWire | IP from our own DHCP; wpctl status shows HDMI |
| 17 | Pi 4 | the same image | boots with kernel8.img; note what fails |
0.8.0 Beta image (2026-10-18)
lordos-0.8.0-rpi5-arm64.img.xz from the v0.8.0-beta tag (46c972a), built natively on the Pi 5 in
about 10 minutes with the LordOS kernels: 532,884,784 bytes, SHA-256
827f3c550eb01f639f3f93f9551b8051a8c6791398b00135f5624d4e5b16724f (2693 MB uncompressed, system
1448 MB). make -C server test on the board: everything passes except npverify-test 35/36, because
the board runs Raspberry Pi's archive kernel, which has no /sys/kernel/btf/vmlinux.
Checked read-only (loop device, ro,noload): config.txt (vc4-kms-v3d, PCIe gen 3, include lordos-case.txt), cmdline.txt (quiet splash, lsm=landlock,lockdown,yama,integrity,bpf),
kernel_2712.img is the LordOS vmlinuz, Plymouth and the lordos theme are in the initramfs,
Theme=lordos, lordos, lord-netperm, lord-fand and lordos-rpi-firstboot enabled, SSH off,
kernel.yama.ptrace_scope = 1, pipewire-pulse module loading off, lordos-user.txt.example, the
remote-desktop switch file handled by firstboot, and the build id 20261018.46c972ac.
Found while checking: the image didn't enable lord-netperm (the ISO and install.sh do), so
the per-app firewall was off on the Pi; build-img.sh enables it now. The LordOS kernel has no
BPF LSM (CONFIG_BPF_LSM is not set, and no BTF), so "No Bluetooth" for Linux apps isn't enforced
on the Pi (lord-netperm reports "bluetooth":false); the network and device programs work. Turning
on CONFIG_BPF_LSM and CONFIG_DEBUG_INFO_BTF in build-kernel.sh is pending. The image has not
been booted on a board yet. (Later: both options are on since 0.8.1's -2+lordos kernel, see "The
LordOS kernel".)
Results on the board (2026-10-18)
Raspberry Pi 5, 16 GB, 32 GB SD card, no fan load, no monitor on HDMI (both HDMI connectors
disconnected). Raspberry Pi OS-style Debian 13 with kernel 6.18.50+rpt-rpi-2712 (16K pages), GCC
14.2, Mesa 26.2.2 from the Raspberry Pi archive, FFmpeg 7.1.5+rpt. Tree copied with rsync; themes built
on the development machine.
| What | Result |
|---|---|
make -C server -j4 (GPU=1, NEON=1) |
✅ every binary: lord-server, lord-sessiond, lord-netd, lord-netperm (BPF with clang), lord-doc, lord-media, lord-vault, lord-maild. 1 min 02 s. One GCC 14 -Wformat-truncation warning (apps.c), fixed: now 0 warnings |
make -C server test |
✅ 23 passed, 0 failed, 0 skipped (with skkdic, rime-data-pinyin-simp, unicode-data and libthai-dev installed), plus engine-test 2642 checks, backup-test 220, vault-test 74, import-test 150 |
NEON (build/canvas-test) |
✅ "NEON matches C". blit 9.90 → 4.33 ms/screen, mask 11.09 → 5.49 ms/screen (2.0–2.3×) |
make -C server test-full |
⚠️ media-test probe/wave/sandbox ✅. doc_evil.sh 20/25: the 5 failures are the filesystem confinement checks (~/.ssh, home, /tmp), because the Raspberry Pi kernel has no Landlock (# CONFIG_SECURITY_LANDLOCK is not set, /sys/kernel/security/lsm = capability). seccomp works on aarch64 (seccomp=1(tsync), no sockets, no fork). sandbox-test skipped for the same reason |
arm64 .deb (DEB_ARCH=arm64 tools/iso/mkdeb.sh) |
✅ 5.0 MB; dependencies resolve on Raspberry Pi OS (its +rpt FFmpeg keeps the Debian package names) |
| lordos.service | ✅ lord-sessiond: display: /dev/dri/card1 (vc4; v3d is card0, drmcard.h picks the right one). With nothing connected the login screen stays headless (kms: no monitor connected) instead of crash-looping. lord-server keeps the lent card and retries on the next DRM uevent (main.c, parked fds). Until 0.8.5 the login screen never opened the uevent socket (hw_start ran only in sessions), so a monitor plugged in after boot stayed black until a restart; the login screen now starts hw without the bus. Retry checked on the board with echo change > /sys/class/drm/card1/uevent (the greeter tries the card again) |
| Idle (login screen, headless) | lord-server 36 MB RSS, 0.6 % CPU; lord-sessiond 4.4 + 2.5 MB; system total 450 MB used of 16 GB; 38–43 °C, throttled=0x0, 2.4 GHz |
| EGL/GBM | V3D 7.1.10.2, OpenGL ES 3.1 (eglinfo -p gbm). LordOS's GPU path on screen not exercised (no monitor) |
| Video (FFmpeg CLI) | HEVC 1080p30 through rpi-hevc-dec (/dev/video19, -hwaccel drm -hwaccel_output_format drm_prime): 300 frames in 0.54 s with 0.12 s of CPU. Software, 4 threads: HEVC 1080p 251 fps, H.264 1080p ~420 fps (synthetic testsrc2 clip: real content is heavier). lord-media only knows VA-API, so inside LordOS HEVC is software for now |
build-img.sh natively on the Pi |
✅ after the key fix (above): 7 min 58 s from the SD card. /var/tmp/lordos-rpi/out/lordos-0.7.0-rpi5-arm64.img.xz, 500 MB (2651 MB uncompressed, system 1412 MB). Kernel 6.18.50+rpt, kernel_2712.img/kernel8.img, initramfs, 386 overlays. The image hasn't been booted yet (the board's only SD is the running system) |
LordOS kernel (build-kernel.sh all, natively) |
✅ 6.18.57-lordos-rpi-2712 (50 min) and 6.18.57-lordos-rpi-v8 (49 min), Landlock built in; installed in a chroot: raspi-firmware's hook copied kernel_2712.img, initramfs, device trees and 388 overlays. Not booted yet (the board's SD is the running system) |
build-img.sh with the LordOS kernels, lord-fand and the switch files |
✅ 8 min 18 s. lordos-0.7.0-rpi5-arm64.img.xz, 503,485,468 bytes (2673 MB uncompressed, system 1431 MB), SHA-256 d47778e6cb8a614b3bb104d14f808dcdf27a4a4f6f61dc50c055cccc9f5cb045. Checked read-only: kernel_2712.img = our vmlinuz, lsm=landlock,… in cmdline.txt, the apt pin, SSH installed but off, lord-fand enabled, verify-board present |
firstboot switch files (in a chroot of the image) |
✅ user + Wi-Fi from lordos-user.txt (SSID with quotes, wifi_country → cmdline.txt), remote-desktop with port=5800 → /etc/lordos/remote/config, kept while the only account had no password, allow=group creates lordos-remote, a bad port=99 falls back to 5673; the files are deleted |
Found and fixed on the board:
- lord-netd vs NetworkManager. Raspberry Pi OS uses NetworkManager (with netplan). lord-netd only
knew systemd-networkd and ifupdown, so it saw
eth0andwlan0as free and started its own DHCP client and a secondwpa_supplicanton them, plus duplicate default routes.managed_by_system()(net/state.c) now also reads/run/NetworkManager/devices/<ifindex>(managed=true);net-test stateshows both as"managed":"system". The LordOS image has no NetworkManager, so there lord-netd still owns the network. - The Raspberry Pi archive key (SHA-1 signatures rejected by apt; see "Building it").
- Default language of the image and first boot: now English, like the ISO (it was Spanish).
Notes for the image:
- Raspberry Pi OS boots with
cgroup_disable=memory; the image'scmdline.txtalready hascgroup_enable=memory(per-app memory limits need it). lsm=landlock,…in the image'scmdline.txtdoes nothing on Raspberry Pi's kernel: Landlock isn't compiled in, and isolation there is seccomp + cgroups + no-new-privs only. Fixed: the image now ships the LordOS kernel withCONFIG_SECURITY_LANDLOCK=y("The LordOS kernel").- The image takes Mesa (25.0.7) and FFmpeg (7.1.5) from Debian. Debian's FFmpeg has no V4L2-request decoding, so the hardware HEVC seen above needs the Raspberry Pi FFmpeg pinned (option 1 in "Video").
Still to do on the board: everything in the checklist that needs a monitor (items 1, 2, 4–8, 10, 15
with screenshots, 16 HDMI audio, 17), the desktop session, and booting the built image from a
second SD card or an NVMe. (Later: a 0.8.4 image was booted from a test SD card for the 0.8.4.1
release test, ISO.md, and the desktop shows on HDMI since 0.8.4.1, see the status at the top; the
measurements with a monitor are still to do.)
Server portability audit (aarch64)
A review of server/ on the development machine, without compiling for Linux ARM. The changed files were checked
with clang -arch arm64 -fsyntax-only -Wall -Wextra against the Linux 6.12 DRM headers and the
EGL/GLES/GBM ones. What follows is the result.
There was nothing x86-specific:
- no SSE/AVX intrinsics or asm in
server/src(blending, blur and scaling are portable C, with 32-bit SWAR); - no
-march=nativein the Makefile.
Fixed:
| Where | What |
|---|---|
server/Makefile |
ARCH (from $(CC) -dumpmachine). On aarch64, NEON=1 by default (-DLORD_NEON; NEON=0 turns it off). QuickJS with -ffp-contract=off: GCC in GNU mode fuses a*b+c into FMA on ARM and would change JS numeric results; our code uses -std=c11, which already turns it off. $(LD) instead of ld for pages.o (cross-compiling). New test build/canvas-test |
server/src/canvas.c |
The rows of canvas_blit (without corners) and of canvas_alpha_mask (text, shadows) are separate functions, with a NEON version (4 pixels per iteration) under LORD_NEON && __ARM_NEON. Bit-for-bit identical to C with valid premultiplied sources: checked with tests/canvas_test.c under emulation (SIMDe) on the development machine, 4000 random rows. Still to do on the board |
server/src/ui/stb.c |
STBI_NEON on aarch64: stb's JPEG uses NEON (on x86 it already used SSE2) |
server/src/term/vt.c:890 |
src[i] >= 0 && … with char: on ARM char is unsigned and -Wextra warns (-Wtype-limits). Now (unsigned char)src[i] < 0x20, the same on both architectures |
server/src/kms.c kms_dispatch |
the DRM event buffer aligned to 8 (it's read with a cast to drm_event_vblank, which has 64-bit fields) |
server/src/drmcard.h (new), main.c, remote/monitor.c |
pick the card with connectors instead of card0 (see above) |
server/src/kms.c/kms.h, gpu/gpu.c |
the primary plane's IN_FORMATS, kms_scanout_ok, EGL's render node for the dmabuf feedback (see above) |
server/src/ui/js_sys.c |
lord.system.info().cpu: on ARM64 /proc/cpuinfo has no "model name". Now it comes from "CPU part" and /proc/device-tree/model: «Cortex-A76 · Raspberry Pi 5 Model B Rev 1.0» |
server/src/sec/sandbox.c (fixed by the sandbox agent, on request) |
SYS_epoll_wait without #ifdef: on aarch64 it doesn't exist and didn't compile. The repeated SYS_read was removed |
Reviewed, no changes:
- Page size (16K on the Pi 5): there's no hardcoded 4096 in
mmap, shm or buffers.- Dumb buffers use
CREATE_DUMB'ssizeandpitch. - WASM memory reserves and protects in multiples of 64 KiB (a multiple of 16K).
- The Monitor uses
sysconf(_SC_PAGESIZE)(monitor/mon.c). - The dmabuf feedback does
memfd+mmapof an arbitrary size, which is valid.
- Dumb buffers use
- Unaligned reads and endianness:
- the OpenType, MaxMind DB, xz, PNG/JPEG (stb), thbrk and IME readers read byte by byte in
big-endian or with
memcpy; - netlink attributes (
net/state.c,nl.c,wg.c) are 4-aligned by the format. - Everything is little-endian, like x86.
- the OpenType, MaxMind DB, xz, PNG/JPEG (stb), thbrk and IME readers read byte by byte in
big-endian or with
- Unsigned
char: the UTF-8 decoders and JSON escapes already useunsigned char(mon.c,nl.c,snd.c,textlayout.c,json.c,wl.c,conn.c); the otherchars are only compared with ASCII. - Structures and ioctls:
input_event(24 bytes),drm_mode_*andEVIOCG*are the same on LP64 (x86-64 and aarch64). There's no fbdev code. SYS_close_rangeandSYS_capsetexist on aarch64.- WASM: float→int conversions check the range before the cast, NaNs are handled by hand
(
QNAN32/64) and loads usememcpy. Runbuild/wasm-teston the board. - QuickJS 2025-04-26 supports aarch64.
pkg/status.calready mapsaarch64→arm64for dpkg and the Store.- Threads:
PTHREAD_STACK_MINis 128 KiB on aarch64; the Monitor threads ask for 512 KiB, which is enough.
Pending for the on-board stage (risks, with file:line):
| Where | Risk |
|---|---|
server/src/main.c:488 (mirror_frame(out.px…) on the CPU path) |
With remote desktop open, it reads from the mapped dumb buffer. On ARM that memory is write-combined/uncached and reading it is very slow; on x86 too, but less so. Better to mirror from s->scene + wl_paint_fullscreen to a buffer in RAM. Measure before touching |
server/src/main.c:484–498 (canvas_copy, line 486) |
The CPU path copies the whole canvas to the dumb buffer (canvas_copy) every frame. At 4K that's 33 MB per frame, too much for the Pi's memory. Copy only the damage |
server/src/canvas.c box_pass/canvas_backdrop_blur |
The vertical pass walks by columns (step = sw), which is slow with the A76's cache. Candidate for NEON (4 columns at a time) or transposing; measure with --profile |
server/src/gpu/gpu.c gpu_formats (known[]) |
Only announces 32-bit RGB: the Pi's SAND128/NV12 video isn't announced (see Video) |
server/src/gpu/gpu.c gpu_device |
That EGL returns the render node with kmsro is unverified. If it returns nothing, it falls back to the first render node, which on the Pi is v3d |
server/src/kms.c read_scanout_formats |
IN_FORMATS with UNIVERSAL_PLANES untested on vc4. If it fails, it stays as before |
server/src/drmcard.h |
GETCONNECTOR forces an EDID read per card at startup (~50 ms). Hotplug: if HDMI is plugged in after boot, lord-sessiond has already chosen the card (vc4 anyway, because it has connectors) |
server/src/sec/sandbox.c |
seccomp: check on the board that no .lpk app dies from a syscall that arm64 glibc uses and x86 doesn't. Landlock: the Raspberry Pi kernel might not have it; cmdline.txt asks for lsm=landlock,…. The shared helper profile (sandbox_apply_helper) uses the same list and is fine on arm64, but has no ioctl: hardware video (V4L2 on the Pi, VA-API on the PC) inside the sandbox needs it (the sandbox agent was told) |
server/src/monitor/mon.c |
The Monitor's "model name" stayed empty on ARM. Fixed: lord.monitor.info().cpuModel now comes from js_sys_cpu_name(), the same one About uses (js_monitor.c) |
server/src/install/install.c:677 |
The installer uses grub-install --target=x86_64-efi. On the Pi it doesn't apply (it's not live, the installer doesn't appear), but it's what would have to change for an ARM64/UEFI installer |
| page size | Some third-party program (not LordOS) assumes 4K: Widevine, box64, old jemalloc. If needed, kernel=kernel8.img in config.txt (4K, a bit slower) |