AquilaOS

A small UNIX-like operating system, written to be read.

AquilaOS is a kernel, a C library and the tools around them. It's meant to be boring: the kernel does what UNIX kernels have done for decades, the plain way, in code small enough to read in full, with a document for each part of it. It runs on x86 and aarch64, on several CPUs, and runs dash, bash, curl, X and Doom.

Start here Try it in your browser

Version
0.0.2
Architectures
x86-64, i386, aarch64
CPUs
up to 32
Standard
POSIX.1-2008
License
Public domain (CC0)
Updated
October 2026

Booting

The x86-64 kernel booting in QEMU on four CPUs, with its console on the serial port. These lines are from the kernel's log, trimmed.

x86: Welcome to AquilaOS!
kernel: 255 MiB of memory, up to 0x0000000010000000
x86_64: 256 MiB in the direct map
apic: local APIC 0 at 0x00000000FEE00000, 1 I/O APIC(s), the first at 0x00000000FEC00000 (GSI 0, 24 pins)
x86: interrupts through the apic
smp: 4 CPUs
vt: 6 terminals of 80x25 on VGA text mode
kdev: registered blkdev 3: ata
net: lo: loopback, 127.0.0.1/8
net: eth0: 52:54:00:12:34:56
e1000: 8086:100E at 0x00000000FEBC0000, irq 11, link up
kernel: loading init process
clock: hpet, 10000000 fs a count
AquilaOS version v0.0.2
login: root

Welcome to AquilaOS!

# uname -a
AquilaOS aquila v0.0.2 Oct 24 2026 15:27:52 gcc 15.3.0 x86_64
#

Start here

You need gcc, ld, cpio and QEMU, nothing else. In about a minute, make run-min builds the kernel with your gcc and boots it with one tiny program: a shell with no C library, each of its commands a system call or two.

  1. Read the documents, in order: how the kernel boots, takes interrupts, manages memory and processes, and the rest, each with pointers into the code.
  2. Change something: add a command to the tiny shell, or a printk() to a system call, and boot it again.
  3. Debug it: make debug boots the same kernel waiting for gdb, and a panic prints a stack trace.
  4. Test it: make test runs the kernel's test suite in QEMU.
  5. Build the whole system: a cross toolchain, then the C library, the shell, the utilities and the ports.

The commands, step by step

Features

Kernel

  • Monolithic, with processes, threads and kernel threads
  • SMP: up to 32 CPUs, with one kernel lock
  • Sessions, process groups and job control
  • POSIX signals, delivered on return to user mode
  • Copy-on-write, demand paging and mmap
  • APIC with MSI; a clock to the nanosecond from the TSC or HPET

Storage and devices

  • ext2 and minix, read and write; tmpfs, procfs, devfs, devpts
  • Virtual terminals on the framebuffer or VGA text mode
  • ATA disks, PS/2 input, 8250 and PL011 UARTs, VESA framebuffer

Network

  • Intel e1000 and e1000e Ethernet
  • IPv4, ARP and ICMP; UDP and TCP (RFC 9293)
  • DHCP client and DNS resolver

User space

  • newlib 4.6, dash, sbase, runit as init
  • About 45 ports: bash, curl with TLS, tcc, Lua, X with dwm and st, Nano-X, UnixBench, Doom

All features and ports

User space Ports bash curl tcc Lua X dwm Nano-X Doom Base system dash sbase runit nc aqbox C library newlib 4.6 with AquilaOS's system calls system call interface Kernel Processes threads, SMPsignals, jobs Memory COW, pagingbuddy, vmem VFS ext2, minixtmpfs, procfs Network TCP, UDPIPv4, ARP Terminals vt, ptyline discipline Drivers APIC, MSI HPET, TSC ATA e1000 fbdev PS/2 8250, PL011 x86-64 and i386 PCs, aarch64 (QEMU virt)
Figure 1. The parts of AquilaOS, from the hardware up. Everything below the dashed line runs in the kernel.

From the blog