Guides
Start here — how to build the system, and how to use and extend it.
The manual
The one-stop reference for using Ouroboros: building it, running it on QEMU and real Parallels hardware, scripted testing, the shell tour, and the complete syscall ABI table.
Guide · the working pathBuild an ARM64 OS from scratch
Nine ordered stages from a UEFI hello world to preemptive multitasking and position-independent userland loaded from disk — the working path only, no bug narratives. Stable Rust and QEMU are all you need.
Reference · Markdown ↗Shell commands
The default shell's builtin commands — syntax, behaviour, and known limitations, command by command. Read on GitHub, where it is always current: the shell gains commands faster than a hand-written abridgement can track them.
Guide · referenceGlossary
Every acronym and term this project leans on — EL0/EL1, GIC, MMIO, PPI, virtqueue, PIE, FAT32, xHCI — defined in one place, grouped by area.
Architecture & reference
The shape of the system and the mechanisms underneath it.
Architecture overview
Six diagrams: the privilege stack, what the kernel keeps versus what it pushes out, the eleven task slots, the MMU-enforced isolation model, a single cat traced across the boundary, and the boot sequence from firmware to EL0.
The process model
How userland programs are loaded, laid out in memory, and structured — the ELF/PIE binary format, the config mechanism, and a guide to writing a replacement program (and the relocation-class traps to avoid). Read on GitHub.
Reference · Markdown ↗Roadmap
The forward-looking plan — the open frontier, the small tails finished arcs left behind, and the north-star directions. It moves every working day, so it is served from the repository rather than copied here.
Reference · Markdown ↗Changelog
The full milestone-by-milestone record, phase 0 to the present, newest first — every completed step with the same level of detail as the postmortems.
Why four of these leave the siteThe shell reference, the process model, the roadmap and the changelog are reference material — worth more current than abridged, and they move on days when nothing else does. They used to be hand-written pages here, and hand-written pages fall behind: the whole site froze for twelve days once, still presenting a superseded release as current, with nothing anywhere reporting it. Serving the Markdown itself removes the copy rather than promising to keep it in step.
Postmortems
Every real bug that mattered, written up in full — symptom, root cause, how it was actually confirmed, and the generalizable lesson. In chronological order, each usable on its own.
From "it doesn't boot" to a real console
Exception vectors, the MMU switch, GIC/timer bring-up, the EL0/syscall boundary, and a console-discovery saga that killed three mechanisms and one whole driver before finding the one that worked on real hardware.
Part 2 · Shell & filesystemFrom a bare prompt to a real, disk-backed OS
A relocation bug found twice before its real shape was understood, a hang with zero diagnostic output, a disk that lied about its own filesystem format, and the write-support arc built on top.
Part 3 · xHCI keyboardGetting a USB keyboard working on Parallels
Seven real, confirmed hardware bugs bringing keyboard input to the kernel — a PCI Command register bit, a real UEFI firmware panic, a page-table assumption, a silently-dropped USB request class, a driver reading the wrong device, and two found weeks later, one of them by a user, not a script.
Part 4 · USB storageGiving Parallels a disk
Proving the hypervisor exposes no storage controller at all, USB passthrough that routes devices by speed and attaches them after your boot scan already ran, a mid-transfer keystroke that would have permanently killed the keyboard, and SCSI Unit Attention found by a hot-plug test.
Retrospective · a different eraEnforce the isolation, rebuild the data flow
A design-led day, not a bug hunt: MMU-enforced per-task isolation and fault containment, then rebuilding every cheap data path enforcement broke — grant/safecopy IPC, a FAT32 offset-write, and the one works-on-QEMU-fails-on-silicon reversal.
Retrospective · driver isolationMoving the console into userland
The second component out of the kernel: a driver the kernel itself depends on (a split, not a move), the gated-primitives-vs-mapped-memory decision, a scheduler lie that routing echo through IPC exposed, a missed client that stranded on real hardware, and verifying pixels by screendump.
Retrospective · scopingScope it down before you build it
Five milestones in one day — an active health-ping, a capability model, program-to-program pipes, a stack guard page, a userland heap — whose lesson is scoping: three shrank when asked whether the clean design needed the hard part, a guard page found a silent overflow on its first test, and a one-build gate proved alloc can't be PIE-linked on stable before a week was spent on it.
A network stack in a day
From no networking to a concurrent HTTP server: the no-IOMMU driver/protocol split, the async-receive primitive a server needs (blocking on frames or messages, then a timer for the RTO), testing loss recovery on a wire that can't lose a packet, a go-back-N sequence-number wrap that stalled transfers, and the guard page catching the stack overflow twice more.
Retrospective · userland maturation/bin, pipelines, and where a command belongs
Builtins became a real /bin of standalone programs with multi-stage pipelines: the ps/kill/wait revert that showed job control belongs in the shell, a capability bitfield collision caught before it shipped, delegation needing less than feared, a pipeline heuristic replaced wholesale, and building a bootable GPT disk just to test one.
exFAT, ext2, and what real hardware revealed
Two filesystems added to the server — each read-only then read-write, all behind one unchanged protocol — with the lessons: an abstraction is only tested by a genuinely different implementation (ext2's inodes), validate against a foreign checker not your own reader, a freed inode's i_dtime that e2fsck misread as an orphan pointer, and a real-hardware pass that found a USB keyboard/storage bug the emulator structurally cannot show.
Research & assessments
Where this project sits against the ideas it draws on — a current self-assessment, and notes on the two outside influences it measures itself against.
Microkernel, protection, fault tolerance
How close the mechanisms actually are — measured against MINIX and Helix OS on three axes, with a consolidated scorecard and a ranked list of what would close each gap. On its one moved service, a genuine microkernel; what's missing is breadth, not honesty.
Assessment · directionsWhere the influences point next
A synthesis across MINIX, Linux, Plan 9, and Helix asking which architectural idea is still worth building — and why Plan 9's per-process namespaces plus a uniform file protocol is the standout: the one mechanism that would unify the servers, the capability model, and delegation instead of piling on a feature.
Research · influenceHow MINIX boots
How a decades-mature microkernel boots and starts its user-space servers — on x86 and on ARM — and where Ouroboros's UEFI-native boot resembles or deliberately diverges from it.
Research · influenceHelix OS's fault-tolerant design
A young, layered, trait-based Rust kernel that makes hot-reload and self-healing first-class primitives — and the real difference between its in-address-space module recovery and MINIX-style process isolation.