Experimental x86_64 operating system written from scratch in C17 and NASM Assembly.
| Current state | |
|---|---|
| Current version | v0.9.0 |
| Latest public release | v0.9.0 |
| Architecture | x86_64 |
| Kernel | Freestanding C17 + NASM Assembly |
| Bootloader | Limine |
| Emulator | QEMU |
| Status | Experimental / Early Development |
| Automated graphics validation | GREEN |
| Manual desktop validation | GREEN |
MIT license. UTAMO Desktop passed the automated release gates and received explicit maintainer acceptance through QEMU/VNC. Release notes describe the delivered functionality, validated artifacts and limits.
Normal boot initializes the kernel and enters the desktop. The UTAMO launcher opens real applications; the taskbar selects existing windows. Click focuses and raises a window, dragging its title bar moves it, and its close button releases the window. Multiple windows can overlap.
- Terminal executes the existing shell commands, with editable input, bounded scrollback and a separate command worker so waits do not block the GUI.
- System Monitor displays real uptime, physical memory, heap, thread and process snapshots about once per second.
- Files browses the immutable VFS and reads supported text files up to 8 KiB. It supports directory pages, parent navigation and a read-only text viewer.
- About UTAMO displays the running version and architecture and has a functional Close button.
The interface uses double-buffered framebuffer graphics, a clipped compositor, PS/2 mouse input, an ordered event queue, a software cursor, opaque windows, the shared bitmap font and a central dark palette. It supports focus, z-order, drag, close, labels, buttons, text fields, lists and keyboard scrolling. It has no resize, minimize, maximize, clipboard, animation or GPU acceleration.
COM1 remains the primary diagnostic output. Desktop ownership suspends the framebuffer text logger; it does not suppress serial diagnostics.
From the project root in Linux/WSL2, using the existing local cross toolchain:
make CROSS_COMPILE="$PWD/toolchain/prefix/bin/x86_64-elf-" run-vncConnect a Windows VNC viewer to 127.0.0.1:5900. This starts no Linux GUI, GTK, SDL or WSLg frontend. QEMU uses a private QMP socket and preserves COM1 output in the invoking terminal and under build/validation/run-*/serial.log.
The default lifetime is 1,800 seconds. Ctrl+C, SIGTERM or timeout stops and reaps the owned VM. Optional settings include QEMU_TIMEOUT=300, QEMU_RAM=512M and QEMU_CPU=qemu64; accepted timeouts are greater than zero and at most 7,200 seconds. Run one VM at a time.
For headless operation with serial diagnostics:
make CROSS_COMPILE="$PWD/toolchain/prefix/bin/x86_64-elf-" run-headlessThe default Limine menu selects Desktop after three seconds; Recovery Console is the second entry. F12 closes a desktop session and returns to recovery. Run the recovery command desktop to enter a new session. Escape dismisses the launcher. Serial is output-only: typing into the host serial terminal does not provide guest PS/2 input.
Desktop requires a supported 32 bpp framebuffer of at least 800x600 and PS/2 keyboard/mouse. The default request is 1024x768. A GUI initialization failure can return to the text console; unavailable baseline framebuffer or keyboard hardware can still stop boot with serial diagnostics.
Manual desktop acceptance is GREEN, recorded on 2026-09-22 for the release ISO. The acceptance record covers input, applications, window management and stable interactive use.
Limine boot, a higher-half x86_64 kernel, COM1 diagnostics, bitmap recovery console, GDT/TSS/IST, IDT, contained user faults, serial-first kernel faults, PIC and nominal 100 Hz PIT.
Physical page allocation, four-level virtual memory, heap allocation, guarded thread stacks and checked resource accounting. Kernel heap capacity and some page tables remain committed by design.
Preemptive kernel threads, round-robin scheduling, sleep/wakeup and deferred resource reaping on one bootstrap processor.
Private CPL3 address spaces, native INT128 syscalls, a static ELF64 loader, a small freestanding runtime and native programs. User processes require NX. Interactive userspace input and a userspace shell are not implemented.
Immutable newc initramfs and VFS, checked file syscalls, PCI enumeration, read-only AHCI/block access and bounded FAT32 snapshots at /disk.
E1000, Ethernet/ARP, IPv4/ICMP, UDP transactions, DHCP and DNS through explicit polling commands. TCP, HTTP and userspace sockets are not implemented.
Double-buffered 32 bpp graphics, clipping and bitmap text, PS/2 mouse/cursor, ordered input, compositor, focus/z-order, draggable and closable windows, bounded widgets, launcher/taskbar, Terminal, System Monitor, Files and About. These features are GREEN in automated testing and the recorded manual QEMU/VNC acceptance.
GUI applications are trusted kernel modules with separate APIs and owned surfaces. Userspace graphics IPC and shared-surface interfaces remain future work.
Both frontends use the same command dispatcher. The graphical Terminal exposes commands that fit its execution model; diagnostic selftests, nested graphical probes, fatal probes and halt require recovery.
| Command | Action |
|---|---|
| help / version / sysinfo | Available commands, running version and system facts |
| mem / pmm / vmm / heap | Real memory and allocator information |
| ps / threads / schedulerstats / processes | Scheduler and process state |
| uptime / sleep milliseconds / echo text | PIT uptime, bounded thread sleep and output |
| ls [path] / cat path | Read immutable VFS content |
| exec path [argument] | Run and await a native ELF program |
| lspci / storage / netinfo | Real enumerated hardware and network state |
| dhcp / ping gateway / resolve name | Existing bounded networking operations |
| clear | Clear this Terminal; recovery clears its own text console |
| desktop | Enter Desktop from recovery |
The shell supports ASCII US input and a 127-character command line. There is no quoting, piping or command history. Native executables have no interactive input syscall. Closing Terminal requests cancellation; an existing filesystem or network operation may finish its bounded wait before releasing the command lease. F12 returns to recovery immediately, which may briefly report busy.
Read Terminal, Files and System Monitor for exact limits.
Use a project path without spaces and the development environment guide. Required tools are x86_64-elf GCC/Binutils, NASM, Make, a host C compiler, Bash, Python 3, xorriso and pinned Limine v8.7.0-binary assets. QEMU/GDB are used for validation. The Makefile does not download tools or use the host compiler for the kernel.
make test-host
make CROSS_COMPILE="$PWD/toolchain/prefix/bin/x86_64-elf-" kernel
make CROSS_COMPILE="$PWD/toolchain/prefix/bin/x86_64-elf-" inspect
make CROSS_COMPILE="$PWD/toolchain/prefix/bin/x86_64-elf-" iso-profilesThe kernel is build/utamo-kernel.elf. The primary development image is build/utamo-os-0.9.0.iso. Alternate console/desktop resolution profiles are under build/validation-isos/ and contain the same kernel and initramfs. Versioned paths change only when the central version header changes. The link step removes local absolute repository paths from non-loaded debug data while preserving loaded bytes and debug offsets. Archive valid build evidence before make clean, which removes build/.
Recovery harnesses need an explicit recovery ISO because the primary ISO boots the desktop:
python3 scripts/test-qemu.py --suite --name recovery-local \
--iso build/validation-isos/utamo-os-0.9.0-console-1024x768.iso
python3 scripts/test-graphics-qemu.py --stage terminal --name terminal-local \
--iso build/utamo-os-0.9.0.iso --ram 256M --timeout 180Use fresh names. Debugging describes the complete headless matrix, graphics stages, resolution profiles and controlled faults.
The historical fresh v0.8 baseline gate passed 36,527 host, 1,987 ELF/ABI and 13,815 QEMU assertions in 41 VMs. These are baseline evidence, not final v0.9 results. Graphics milestone results and artifact hashes are in the campaign state. The campaign final stamped 0.9.0 gate passed 41,349 host, 2,288 ELF/ABI and 15,357 QEMU assertions, plus two runner lifecycle checks: 61 VMs total, zero final failures, all reaped. Stress passed at 64/256/512 MiB and 1024x768/800x600 with 496 real window lifetimes and exact warmed heap/PMM/VMM accounting. Final report, hashes and limits. Counts identify recorded assertions, not unique tests or coverage. The separate release preparation record records the fresh release checks and manual acceptance gate.
Framebuffer backend <-> canonical heap backbuffer
|
clipped 2D primitives
|
compositor / window manager
|
widgets / desktop shell
|
Terminal / Monitor / Files / About
PS/2 IRQ bytes -> ordered event decoder -> desktop or recovery
Shared shell dispatcher -> one command worker -> scoped Terminal output
COM1 diagnostics remain independent
The GUI composes only dirty work, with cursor last and full-frame presentation. It sleeps between work opportunities. Up to 16 windows are supported. Monitor and uptime use PIT time, not a wall clock or invented CPU percentage.
Heap capacity, empty kernel page tables and the first Terminal worker remain allocated by design. Leak gates compare warmed live allocations and PMM/VMM accounting. No global W^X is claimed: inherited HHDM aliases retain limitations.
UTAMO remains experimental. There is no SMP, POSIX/Linux compatibility, userspace shell, TCP/HTTP, FPU/vector context, USB input, disk writing or arbitrary-hardware support. Networking is serialized polling during explicit commands, not a background server. Files supports bounded ASCII text and immutable mounts. UEFI, hardware and manual desktop acceptance are separate from headless QEMU evidence.
- Graphics, window manager and widgets
- Desktop, Terminal, Monitor and Files
- Graphics Campaign state, final report and validation summary
- Architecture, roadmap, development log and changelog
- Debugging, tests and development environment
- Memory, heap, scheduler, processes and syscalls
- VFS, ELF, userspace, storage and networking
- Historical v0.8 engineering report and v0.8 evidence
UTAMO OS is MIT licensed. Third-party notices, contribution guidelines and security policy remain applicable.