codexOS

Inspiration

I wanted to build an OS that actually boots — not a kernel that stops at a serial “Hello”. codexOS started from a simple bet: can Rust carry a full path from UEFI firmware through a resident kernel to a live GUI desktop, with a repeatable loop of build → image → QEMU → framebuffer → serial debug? The goal was one continuous system story: boot, memory, drivers, filesystem, networking, and signed updates.

What it does

codexOS is a bootable Rust GUI operating system that runs under QEMU/UEFI. It:

• boots via a UEFI loader, stages a standalone KERNEL.ELF, and chainloads into a resident kernel
• renders an interactive framebuffer desktop with keyboard focus, mouse dragging, and a terminal shell
• manages memory with a reclaiming heap, physical pages, HHDM, and W^X page permissions
• runs isolated Ring 3 processes with syscalls, preemptive scheduling, and address-space reclamation
• persists data through virtio-blk and CodexFS (snapshots, CRC checks, dual superblocks)
• brings up virtio-net with DHCP, DNS, TCP/HTTP, and ICMP
• supports signed A/B kernel updates, GPT/ESP images, and automatic fallback recovery

How we built it

The repo is a Rust workspace with clear layers:

1. uefi-loader — builds the bootable image, stages KERNEL.ELF, and supports handoff / chainload
2. Shared runtimes — boot-runtime for early serial, pages, and boot VM; desktop-runtime + gfx for the desktop loop
3. Resident kernel — heap, page tables, interrupts (GDT/TSS/PIT), PS/2 input, PCI inventory, virtio-blk / virtio-net
4. System services — CodexFS, Ring 3 ELF loading, scheduling, terminal shell
5. Engineering loop — xtask unifies build / image / run / smoke; release tooling covers signed updates and recovery

Day to day we package with cargo xtask, boot in QEMU+OVMF, debug over serial, and gate regressions with smoke tests.

Challenges we ran into

• Loader → kernel ownership — heap, page tables, and BootInfo must transfer cleanly; a bad handoff can still draw a desktop and fail later
• Firmware-detached input — PS/2 keyboard and mouse had to work without UEFI helpers; QEMU monitor injection made that path testable
• Filesystem consistency — append-only snapshots, CRC, alternating superblocks, and flush-then-reread checks; cold-boot smoke tests require a continuous on-disk counter
• Network stack correctness — checksums, ARP, DHCP, DNS, and TCP handshakes fail quietly when any step is wrong
• Update and recovery — signed-slot fallback and boot-state scan recovery had to be proven together with the install path

Accomplishments that we're proud of

• A real UEFI → resident-kernel boot path with interactive GUI, not just a bootloader demo
• Ring 3 isolation, W^X mappings, and a versioned syscall ABI that survive smoke boots
• CodexFS with integrity checks and durable cold-boot verification
• End-to-end networking: lease, DNS, TCP/HTTP client and listener paths
• Signed A/B updates with anti-rollback, GPT/ESP layout, and automatic recovery

What we learned

Operating-system ideas only count when they become observable behavior. We learned how fragile firmware handoff is, how much discipline W^X and process isolation demand, and why persistence and update security belong in the boot path — not as late add-ons. The lasting lesson: if a smoke test cannot catch it, it is not done yet.

What's next for codexOS

• Broader physical-machine drivers (storage, network, USB HID)
• Richer filesystem allocation and access-control semantics
• A general socket API, multi-connection services, and TLS
• Application packaging and signing policy
• UEFI Secure Boot enrollment, hardware-backed signing, and independent security review

Built With

• cargo
• ed25519
• elf
• fat
• filesystem
• framebuffer
• gpt
• kernel
• networking
• operating
• ovmf
• pci
• ps/2
• qemu
• rust
• sha-256
• systems
• tcp/ip
• uefi
• virtio
• x86-64