Lunaix: a POSIX-flavoured kernel written from scratch by one person

One author, no recycled code, and an explicit POSIX ambition

Lunaix describes itself as a simple yet naive, POSIX-compliant hopefully, operating system from scratch, and the README is unusually honest about what that means. The kernel was started in 2022 and written entirely from scratch, and the project states plainly that no code was copy-pasted or recycled from other operating system projects or tutorials. The author's account of the motivation is personal rather than competitive: it began as a challenge to learn operating system theory and explore advanced kernel features through original design, developed solo and part-time, guided only by hardware specifications and a well known textbook on modern operating systems. The stated ambition is POSIX compliance, with performance and modernity in mind and independent architectural thinking applied throughout. The audience the project invites is a kernel hobbyist looking for a fresh take or tired of mass-produced tutorial-style projects, and there is an online video course on the design in Chinese for anyone who wants the narrative rather than the code.

The memory manager does copy-on-write, highmem and reverse mapping

The feature list is where the ambition becomes concrete, and the memory management section is the densest part of it. Lunaix implements an architecture-neutral abstraction on top of x86_32 and x86_64 with Aarch64 marked as work in progress, and adds highmem support, copy-on-write, page sharing, explicit huge pages, on-demand paging, compound pages, a slab-style object allocator, and inter-process address space access. The reverse mapping structure is worth calling out because it is the feature that makes several of the others practical: knowing which physical page backs a given virtual address is what makes copy-on-write faults and page sharing tractable. Memory compaction is listed as work in progress. The design also separates the machine-independent layer from the architecture specifics, which is why the same virtual filesystem, driver framework and scheduler code can sit on top of more than one instruction set architecture.

Preemptive scheduling with protection levels and signals

Multi-tasking in Lunaix is fully preemptive, with protection levels, process isolation, native threading and a signal mechanism, and the scheduler is described as round-robin for now. Kernel-level multi-tasking is present, meaning threads that run inside the kernel, and there is a taskfs, a file system interface that exposes processes and threads as ordinary files so that user space tooling can inspect them. That last point is a design decision with practical consequences: a process listing becomes a file read rather than a special system call, which is the kind of unification that makes a kernel feel coherent when you go looking for something. The scheduler being round-robin for now is the honest limitation, and it is stated in the feature list rather than hidden in a design document. On the fault-handling side, the project lists stack backtracing with symbol resolution, stack unwinding for nested exceptions, CPU state dumping, and deadlock and hung-up detection.

A virtual filesystem with ext2, iso9660 and a page cache

The file system layer is POSIX-compliant at the interface and built around a virtual file system framework with a mounting mechanism underneath. On top of that sit ext2 in both revision 0 and revision 1, iso9660 with rock-ridge support, and twifs, described as a kernel state file system interface that exposes internal kernel state as files. Performance in the file path comes from a page cache for file IO plus inode and dnode caching, and a separate caching infrastructure provides LRU replacement, pooling, and a kernel daemon for dynamic and transparent cache management. Putting a kernel state file system next to the real ones is a nice touch for a learning kernel, because it means you can inspect the scheduler or the memory manager with ordinary file tools. Device management follows the same pattern: a unified IRQ framework, a unified driver framework for heterogeneous devices, a modular driver model with compile-time toggling, an asynchronous operation model, and devfs as the device file system interface.

Drivers cover serial, SATA, PCI and VGA, with an ARM path in progress

The built-in driver list shows how far the porting effort has gone. Architecture-neutral drivers include a UART 16550-compatible driver, Serial ATA with AHCI, PCI 3.0, PCIe 1.1 and standard VGA. The Intel x86 side adds an RTC on the Intel PCH, an IOAPIC IRQ controller, the APIC timer and the legacy i8042 keyboard controller. The ARM side has a GICv3 interrupt controller and a PL011 UART marked as work in progress, which is consistent with Aarch64 also being in progress. The IDE driver is absent and SATA takes its place, and block IO is handled through a unified blkio interface with request packet caching and asynchronous operations. Serial IO is present with a POSIX-compliant model, and the console can be pointed at either a serial port or VGA text mode through kernel parameters, which is how the demonstration images in the project documentation were produced.

Building needs gcc, binutils, make and python, and live_debug.sh is the shortcut

The dependency story is deliberately thin. A build essentials installation plus python is described as sufficient, with gcc recommended at version 12 or newer, plus binutils, make and python at version 3.11 or newer. Two environment variables drive the build: ARCH selects one of the supported architectures, and CX_PREFIX names the gcc prefix for the corresponding architecture when cross compiling. The available make actions are a kernel binary build, a stock root filesystem build, a clean, a configuration tool and a reconfiguration that reverts to defaults and restarts configuration. A successful build produces the kernel binary in the build directory. The README is emphatic about what that is and is not: this is the kernel, not a bootable image, and it requires a bootloader to boot and to specify the root filesystem. That single sentence reframes the whole project, since it is a kernel you develop, not a distribution you install.

$ export ARCH=x86_64

For anyone impatient, or who simply wants something running, the project provides a live_debug.sh script in the repository root that brings the system up with default parameters, and the author uses it for debugging. That script is the fastest route to a working system and it is also a way of sidestepping the two things the manual path makes you do: configure a root filesystem and tune kernel parameters. The quick start still assumes a Linux or other Unix-like shell environment and expects you to be able to sort out trivial package issues yourself. The documented checks are explicit, and each one is a single command: confirm the architecture, check the python version is at least 3.11, check what gcc -dumpmachine reports and confirm it says x86_64-linux-gnu or something resembling x86_64, and check that qemu-system-x86_64 is on the path. The listed checks are short because the point is to fail early on a missing tool rather than halfway through a build.

$ python --version
$ gcc -dumpmachine
$ which qemu-system-x86_64

Where a from-scratch kernel is the wrong project

The limits are structural and the project states most of them itself. It is a kernel, not an operating system you can install on a laptop, and the project is candid that it is a hobby kernel with a naive approach. The POSIX compliance is described as hoped for rather than certified, and the reference to Modern Operating Systems as guidance makes clear that this is a learning artifact, which is also its main appeal. Several subsystems are explicitly unfinished, including Aarch64, memory compaction, the PL011 UART driver and the multi-ISA story generally, so a project that needs ARM support today is looking at a port, not a configuration. The alternative to adopting it is not a product comparison but a method comparison: tutorial-derived kernels teach by reproducing a known good design in a fixed order, while an original kernel gives you the author's own abstractions, with the trade-off that you inherit his design decisions without the benefit of a community that has already stress-tested them. For reading, the second is more interesting. For shipping, neither helps you.

Maintenance, licence and the documentation that still needs writing

The repository is not archived, and the last push was on 2026-08-23. There are no GitHub releases, which fits a project that distributes source rather than artefacts, and the default branch is master. The licence is MIT, which is permissive for a kernel and means the code can be studied, reused and modified with attribution, a meaningful contrast to the copyleft licences most kernels carry. The repository layout tells you where the depth is: the kernel sources sit under a lunaix-os directory, docs holds the written documentation, slides holds presentation files, and a reference directory holds supporting files, and there is a .gitmodules file indicating that at least one dependency is tracked as a submodule. The documentation index is small but pointed, with an internal tour of how Lunaix works and a syscall number assignment table, and the README asks readers to keep in mind that the documents are still work in progress and missing localisation. The project has no separate home page listed, so the repository and the Chinese-language video course are the primary entry points.

Editorial conclusion

Adopt Lunaix if you are a kernel hobbyist who wants to read an original design rather than follow a tutorial lineage, or if you want a compact codebase to study preemptive scheduling, reverse mapping and file system caching side by side. Do not adopt it for anything that must actually run, since the build produces a kernel binary that still needs a bootloader and a root filesystem, and the feature list itself marks several areas as work in progress. Before you start, confirm you have a Linux or Unix-like shell, gcc 12 or newer and python 3.11 or newer, and read the syscall table document so you know the interface surface you are working against.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Minep/lunaix-os on GitHub
4. README