SavanXP is an experimental operating system for x86_64, booting on UEFI or
legacy BIOS firmware through the Limine bootloader, with its own kernel in
C/C++ and a native Bash/CMake workflow.
It boots to a working graphical session with its own window manager, a userland
shell, a persistent volume mounted at /, a minimal POSIX base, built-in
apps, and support for external apps compiled against the SDK in this repo.
Current version: v0.4.3 · Changelog ·
MIT license
On Linux, from a clean checkout:
./build.sh build # configure, compile, stage SxFS and EFI artifacts
./build.sh run # boot the staged image in QEMU
./build.sh smoke smoke # run the core QEMU smoke scenarioThe native path uses tools from PATH (or CMake cache overrides); see
Building with Bash and CMake. The versioned ports are
built independently with ./ports/doomgeneric/build.sh,
./ports/ffmpeg/build.sh and ./ports/ccleste/build.sh.
x86_64kernel booting over UEFI or legacy BIOS via Limine: the ISO is hybrid, and./build.sh runboots the development tree with UEFI (OVMF).- It runs on real hardware: the ISO, written to a USB stick, boots a desktop PC and is driven by its USB keyboard and mouse (Running on real hardware).
- Framebuffer console and early serial output.
- Userland with
ELF64processes, syscalls and a preemptive scheduler. - Shell with
pipes, redirections and basic builtins. - NT-style graphical session, started and kept alive by a native session
manager (
sessiond): its own window manager (windowd) with an Alt+Tab switcher, and the shell as clients of it: onedesktopprocess (wallpaper, a taskbar listing the open windows, the Start menu on Ctrl+Esc, and volume, clock and ES/EN keyboard layout popups) plus Program Manager. - Built-in apps: Files, Notepad, Paint, Calculator, a Command Prompt in the style of Windows 2000 (docs/desktop/CONSOLE.md, Ctrl+Alt+T), Web Viewer (an in-tree browser prototype), Add/Remove Programs, System Properties, Disk Management (docs/userland/DISK_MANAGEMENT.md) and a Task Manager with live CPU and memory per process (how it measures). Games: Minesweeper and Nightwood, a 3D forest (docs/userland/NIGHTWOOD.md). Media Player is an optional port (docs/media/MEDIA_PLAYER.md).
- Persistent
SxFSvolume mounted at/; FAT volumes (the boot volume at/boot, and disks or USB sticks Disk Management mounts under/mnt). - POSIX base and SDK v1 for compiling external applications.
sxgfx2D graphics layer for surfaces, painter and rect sets.- USB: xHCI controllers, keyboards, mice and tablets next to the PS/2 and virtio ones, USB sticks as disks, hubs, and devices plugged in or pulled out while running (docs/roadmaps/done/USB_ROADMAP.md).
- Drivers for network (rtl8139, virtio-net), audio (AC'97, virtio-sound),
display (the firmware framebuffer, virtio-gpu) and storage (AHCI, IDE,
virtio-blk, USB, NVMe). NVMe disks are read-only unless the boot entry
carries
nvme-rw(docs/kernel/NVME.md).
On Linux, install Clang/LLVM, CMake, Ninja, GNU Make, Python 3 with Pillow,
Git, QEMU, OVMF and xorriso, plus Meson and pkg-config for the FFmpeg port. build.sh resolves these tools from PATH and
fetches the pinned Limine checkout when needed. Distribution package names and
QEMU backend details are in Building on Linux.
Python (with Pillow) is used on every build to convert checked-in PNG assets
into C headers and SXE resources. It never redraws the icons: the checked-in
PNGs are the source of the art.
CMake tool locations can be overridden in the cache or with the corresponding
SAVANXP_* environment variables.
./build.sh buildThat command:
- compiles the kernel and the internal userland
- generates the
initramfs - prepares the EFI boot image
- creates
build/disk.imgif it does not exist yet - syncs the internal contents onto the persistent volume
Important: a normal build must not recreate build/disk.img unconditionally.
The native build applies changes to a validated sibling candidate and installs
it atomically. The persistent image is kept across builds except on real
corruption or a format incompatibility.
To build without the test and diagnostic apps (keytest, gfxdemo, smoke, ...),
use --no-test-apps: those binaries stay out of the rootfs and the desktop menu
is built without their entries. The automation commands (smoke,
windowd-smoke, ...) always include them, because their harnesses depend on
them.
./build.sh build --no-test-appsGenerating a bootable ISO:
./build.sh isoThe ISO lands in build/SavanXP.iso. That command requires xorriso from
PATH (or SAVANXP_XORRISO) and uses the EFI tree the build already prepared.
It is a hybrid image: it boots on UEFI and on legacy BIOS (VirtualBox with EFI
off, SeaBIOS in QEMU), and tools/iso_boot_test.py --iso build/SavanXP.iso
boots it both ways in QEMU.
To keep the disk's data when booting under VirtualBox or another hypervisor,
attach build/disk.img as an extra disk as well.
The ISO boots a real PC from a USB stick. First reached on 2026-11-06 on an
AMD desktop (Zen, 400-series chipset, UEFI): the system came up from the
stick and its USB keyboard and mouse drove the desktop. The machine needs an
x86_64 CPU with NX, and Secure Boot turned off (Limine is not signed).
On Linux, write the ISO to the whole stick, not to a partition (this erases
it; check the device name with lsblk first):
sudo dd if=build/SavanXP.iso of=/dev/sdX bs=4M conv=fsync oflag=direct status=progressOn Windows, Rufus does the same in its DD image mode. Then boot the stick from the firmware's boot menu. The Limine menu waits 3 seconds and offers two more entries: boot log on screen shows the kernel log instead of the splash, the only way to see where a boot stops on a machine without a serial port, and no USB leaves the USB controllers to the firmware.
The live system runs from memory and keeps nothing across reboots. It does
see the machine's SATA, NVMe and USB disks (NVMe ones read-only). At boot it only
reads them, with one exception: a disk holding an SxFS volume is mounted as
/ instead of the live system, and mounting replays its journal. After that,
only Disk Management writes to a disk, and only when asked to. What a
machine needs, and what is known about each hardware target, is in
docs/hardware/REAL_HARDWARE.md.
./build.sh run
./build.sh run --accel kvmThe native launcher uses TCG by default and KVM when requested.
The QEMU machine is assembled with "base" hardware by default: standard VGA,
PS/2 mouse and keyboard, AC'97 audio, an AHCI (SATA) disk and an rtl8139 NIC —
the same set VirtualBox emulates. This way the kernel exercises the fallback
backends (fb_gpu, ps2, ac97, ahci, rtl8139) without leaving QEMU.
SAVANXP_DISK_BUS=ide puts the disk on legacy IDE instead, for the ata driver, and
SAVANXP_DISK_BUS=nvme on an NVMe controller, for the nvme driver. Bringing the
machine up with paravirtualized devices (virtio-vga, virtio-tablet,
virtio-keyboard, virtio-sound, virtio-blk, virtio-net) has to be asked for
explicitly:
./build.sh run --virtioThe switch applies to every command that launches QEMU (run, debug, the
smokes and gpu-soak). The audio harnesses that measure one specific driver
(ac97-count, virtio-count, ...) force their device and ignore it.
--gl (or SAVANXP_GL=ON) is the virtio machine with virtio-vga-gl, which
offers virgl to the guest. It needs a QEMU built with virglrenderer and a GL
display (egl-headless for the smokes). The kernel logs virtio-gpu: virgl capset=... when it gets one; 3D work is tracked in
VIRGL_ROADMAP.md.
--usb (or SAVANXP_USB=ON) adds an xHCI controller with a USB keyboard and
tablet, on either machine. The usb-*-smoke scenarios drive the USB stack
against it, with a machine that has no PS/2 controller at all
(USB_ROADMAP.md).
Other available targets:
./build.sh debug
./build.sh smoke
./build.sh windowd-smoke
./build.sh gpu-soak
./build.sh cleanrunstarts QEMU with a graphical session and serial output on the terminal.debugkeeps the boot flow oriented towards debugging.smokeruns an automated headless test and leaves logs inbuild/.windowd-smokeexercises the graphical compositor.gpu-soakstresses the GPU presentation path.cleanremoves generated build outputs while preserving the persistent disk image and external artifacts.tools/shoot.sh --scenario desktopperforms the native visual/QMP check on a disposable image copy.
The system enters init and then sh as the main shell. To see the base state
of the system from inside the guest:
sysinfo
df
ls /
Useful commands in the current userland:
shsysinfodfwindowdkeytestmousetestgputestpingnetinfobeepaudiotest
The basic file utilities are small in-tree programs too
(subsystems/posix/userland/coreutils): ls, cat, echo, mkdir [-p],
rm [-rf], mv, cp [-r], ps, true, false and sleep.
The recommended flow for testing your own programs does not require rebuilding
the initramfs. External apps are compiled against the SDK and installed
straight into build/disk.img, normally under /bin.
./build.sh build
./tools/build-user.sh --source sdk/hello/main.c --name hello
./build.sh runUse --destination /bin/NAME (or another path below /) when the
program should not use the default /bin/NAME location. A SUN program,
built with --native, installs as /bin/NAME.sxe; the shell runs it as
NAME too (docs/userland/SXE_FORMAT.md).
Inside SavanXP:
which hello
hello
There is also a wrapper that compiles, installs and boots the system in one step:
./tools/run-user.sh --source sdk/hello/main.c --name helloIncluded examples:
sdk/hellosdk/fsdemosdk/gfxhelloports/doomgeneric
SavanXP uses a persistent disk image at build/disk.img, mounted as /
inside the system through SxFS.
This makes it possible to:
- keep files across reboots
- install external binaries in
/bin - store assets and persistent data under
/
Inside the guest:
echo hello > /notes.txt
sync
cat /notes.txt
The repo workflow protects this persistence: ./build.sh build must not
delete external applications that are already installed, nor persistent assets
such as the ones doomgeneric uses.
arch/: architecture-specific codekernel/: kernel and base subsystemssubsystems/posix/: POSIX layer, SDK and main userlandsystem/: native (SUN) programs: the platform services (compositord,windowd,sessiond,elevationd), the Command Prompt, Disk Management, Task Manager and Nightwoodlibsxfs/: portable core of theSxFSfilesystem andsxfs-cli, the host tool that does all disk image writingrootfs/: contents of theinitramfs, the rescue system published under/rescuediskfs/: initial contents of the persistent volumesdk/: SDK examplesports/: versioned official third-party ports with independent build flowstools/: host-side scripts and development utilitiesvendor/: third-party dependencies
docs/README.md— index of every design documentdocs/build/BUILD_CMAKE.md— native build graph and commandsdocs/build/BUILD_LINUX.md— native host requirements and QEMU setupdocs/userland/SYSTEM_LAYERING.md— which layer is written in which language, and whyAGENTS.md— working rules for this repository (changelog format, persistence guarantees, minimum verification)
SavanXP is well past the minimal-boot stage. Today it offers a coherent base to keep building on:
- its own kernel and userland
- a usable initial desktop
- a graphics path under a compositor
- real persistence over
/ - support for ports and external applications
- a first boot on real hardware, with its own USB stack
It is still an experimental system, with APIs and subsystems in flux, but it is already aiming to be a consistent, demonstrable working base.

