A 32-bit i386 operating system written from scratch in C. Boots on bare hardware (and inside QEMU), runs preemptive multitasking with SMP, talks TCP/UDP/DHCP/DNS/NTP/TLS 1.3, hosts in-guest HTTP/HTTPS/SSH/IRC servers, supports USB HID + Mass Storage, and ships a Unix-like userland with fork/exec, pipes, jobs, signals, sandbox/limits, a JSON-RPC daemon, and an in-guest ptrace debugger.

    _       _                  _    ___  ____
   / \   __| |_   _____ _ __ | |_ / _ \/ ___|
  / _ \ / _` \ \ / / _ \ '_ \| __| | | \___ \
 / ___ \ (_| |\ V /  __/ | | | |_| |_| |___) |
/_/   \_\__,_| \_/ \___|_| |_|\__|\___/|____/

v1.0.0 — 171 sessions of work. Reading order, subsystem breakdown, and per-feature session logs are in docs/INDEX.md. v1.0 readiness rubric is in docs/158-v1.0-readiness.md.

Prerequisites: a recent QEMU (10.x+), an i386 cross-toolchain (mingw-w64 on MSYS2 works), and bash. Tested on Windows 11 / MSYS2 UCRT64. Linux should work with minor build.sh tweaks.

# Build the disk image (bootloader + kernel + AdventFS).
bash build.sh

# Minimal run — graphical QEMU window, USB keyboard, single CPU.
qemu-system-i386 -drive format=raw,file=os.img -serial stdio -m 32 \
    -smp 1 \
    -device piix3-usb-uhci,id=usb0 \
    -device usb-kbd,bus=usb0.0

# Full run — SMP=2, networking, USB storage.
qemu-system-i386 -drive format=raw,file=os.img -serial stdio -m 32 \
    -smp 2 \
    -netdev user,id=net0,hostfwd=tcp::8080-:80,hostfwd=tcp::7000-:7000,hostfwd=tcp::2222-:2222 \
    -device rtl8139,netdev=net0,mac=52:54:00:12:34:56 \
    -device piix3-usb-uhci,id=usb0 \
    -device usb-kbd,bus=usb0.0 \
    -drive id=usbfs,file=usbfs.img,format=raw,if=none \
    -device usb-storage,drive=usbfs,bus=usb0.0

Hostfwd maps in the full-run command:

• localhost:8080 → in-guest httpd
• localhost:7000 → in-guest agentd JSON-RPC
• localhost:2222 → in-guest sshd

You can also curl http://localhost:8080/ from the host once the OS is up.

boot/        16-bit real-mode bootloader (assembly)
kernel/      i386 protected-mode kernel (C + a little asm)
user/        Userland programs (sh, init, coreutils, daemons, selftests)
libc/        Dynamically-linked libc (sessions 9+; `libc.bin` cached at boot)
libuser/     Static helpers linked into every user binary
libcrypto/   From-scratch crypto: SHA-256, AES, P-256 ECDH, RSA, HMAC, X.509
libjson/     Streaming JSON parser/emitter for the agent-RPC + structured pipelines
include/     Shared kernel+userland headers (io, types, etc.)
fs/          Files included at mkfs time (passwd, ssl certs, agent.tools.json…)
docs/        Per-session technical deep dives (171 docs; index at docs/INDEX.md)
mkfs.py      Builds the AdventFS image
build.sh     Orchestrates the whole build

The project advances in numbered "sessions" — each session is a focused chunk of work that lands as one or more git commits plus a docs/NN-name.md deep-dive explaining the design choices and the bugs found. Sessions are not strictly chronological with commit dates; some run a few hours, others span days when a hard bug is being chased.

171 sessions in, all five paths (A/B/C/D/E) are complete; see docs/INDEX.md for the full grouped session log. Highlight sessions to start with:

• Session 1 — Bootloader + 32-bit kernel — how the system boots
• Session 14 — fork, exec, wait — the Unix surface lands
• Session 36 — TLS 1.3 + HTTPS — real-world crypto
• Session 50 — SSH server — ssh in, get a shell
• Session 64 — Agent JSON-RPC tooling — agentd surface
• Session 80 — SMP=2 deadlock fixes — -smp 2 finally usable
• Session 90 — A C-subset compiler from scratch — cc
• Session 111 — Window manager daemon — wmd compositor lands
• Session 134 — wmterm terminal emulator — terminals
• Session 169 — Stability + flake hunt — how the test discipline works
• Session 172 — v1.0 readiness assessment — the rubric this release passed

AdventOS is a personal-project OS. It targets QEMU 10.x and the bochs/seabios BIOS that ships with it. Real-hardware boot has worked in the past but isn't continuously tested. The OS is single- architecture (i386), single-FS (AdventFS), single-machine — no clustering, no live migration, no certifications.

All five development paths reached completion at v1.0.0:

• Path A — Usable Unix (sessions 83–86, 136–140): bash-compat shell, mid-line editing, control flow, functions, arithmetic, parameter expansion, tab completion, history recall, brace expansion. Real .sh scripts work.
• Path B — Self-hosting compiler (sessions 90–106, 121, 125, 133–137): cc (1500-line C-subset compiler from scratch) + tcc (vendored real TinyCC). Both emit ELF32 that runs inside AdventOS. cc has reg-allocator, const-fold, peephole, DCE.
• Path C — Graphics + WM (sessions 107–169): VBE framebuffer → libgfx → wmd compositor → 10+ apps (wmterm, wmedit, wmcalc, wmpaint, wmview, wmfiles, wmsysinfo, wmps, wmclock, …) → scrollback, selection + clipboard, 256-color terminal, snap preview, workspaces, USB tablet.
• Path D — Scripting (sessions 87–89): Lua-syntax interpreter (lua). ~1100 lines, pcall/error, closures, mark-sweep GC, multi-return, generic for k,v in pairs(t).
• Path E — Drivers (sessions 118–127): virtio family (blk/scsi/net/rng/console/balloon/9p), e1000 NIC, AHCI SATA with NCQ, NVMe (PRP DMA), USB UHCI + EHCI, USB class drivers (HID, MSC, CDC-ACM, CDC-ECM), AC97 audio.

The driver tier covers: storage (ATA / AHCI-NCQ / virtio-blk / virtio-scsi / NVMe / USB MSC over either HC), net (rtl8139 / virtio-net / e1000 / USB CDC-ECM), USB (UHCI + EHCI both fully integrated; HID + MSC + CDC-ACM + CDC-ECM class drivers), filesystem passthrough (virtio-9p read/write/rename), misc (virtio-rng / virtio-console / virtio-balloon / AC97 audio).

Per-feature reading order is in docs/INDEX.md. The v1.0 readiness rubric is in docs/158-v1.0-readiness.md.

• x86_64, ARM, RISC-V — i386 only, by design.
• Self-hosting the kernel — neither cc nor tcc is wired to build kernel/ from inside the OS. Both can build small programs end-to-end.
• xHCI / USB 3.0, virtio-gpu hardware accel, EHCI periodic schedule (for true iso transfers). Standalone follow-ups; none gate v1.0.
• Real Lua features: metatables, coroutines, capture-by- reference closures, string patterns, math lib. Path D shipped the subset that's useful for small scripts.

MIT. Copy it, fork it, ship it, learn from it.