UnoDOS

One source tree, one design, twenty-two machines, from an IBM PC/XT with an 8088 to the modern laptop on your desk.

UnoDOS is a family of graphical operating systems. It began as a GUI-first, 16-bit real-mode OS written entirely in x86 assembly, fitting a kernel, a window manager, two filesystems, cooperative multitasking and a full application set on a single 1.44 MB floppy. It has since grown into a contract-driven family of ports spanning home computers, consoles, handhelds, single-board computers and a phone, and its flagship is now pc64: UnoDOS running bare-metal on any modern 64-bit PC, on its own drivers, with its own network stack, browser, office suite, compiler and hypervisor.

Prebuilt images for every platform are on the releases page: a hybrid ISO and USB disk image for modern PCs, cartridge ROMs for the consoles and handhelds, disk images for the home computers, and SD-card payloads for the boards. Most of them run in an emulator within a minute; the user manual walks through booting real hardware, including one-click USB flasher apps for Windows and macOS.

What has actually been verified is a separate question from what builds, and PLATFORMS.md is the ledger that answers it: per platform, what has booted on real hardware (and on which physical machine), what is emulator-verified only, and every known gap.

pc64 boots bare-metal on essentially any x86-64 PC made since ~2007. UEFI plays the role the BIOS plays for the classic OS: the firmware hands over a framebuffer, a keyboard and the boot volume, and then, on most machines, UnoDOS calls ExitBootServices and the firmware leaves. From that point the OS runs entirely on its own drivers. A hybrid disk image boots the same OS on legacy-BIOS machines too.

The shell is built on unoui, the family's cross-platform widget toolkit: a windowed desktop with a taskbar, virtual desktops, window snapping, an animated Alt-Tab switcher, desktop icons and a programs menu. Ten themes are live-switchable, from Aurora (the modern flat default, in light and dark) to faithful retro looks (Mac OS 7, 1-bit Mac Plus, Windows 3.1, Amiga Workbench, C64, Apple II, NeXTSTEP). Text is kerned, anti-aliased TrueType with bundled open fonts, and every control is reachable by pointer or keyboard.

UnoWord, UnoCalc, UnoShow: an Office 97-class suite that reads and writes the real Microsoft binary formats (.doc, .xls, .ppt) through the in-tree unodoc library.

Browser: HTML, Markdown and CSS rendering with cookies, cache, find and save, HTTP and CA-validated TLS 1.2 HTTPS, and two switchable JavaScript engines: the in-tree unojs bytecode VM and vendored quickjs-ng, with a libcss-based layout engine option behind the same seam.

Studio: an IDE that runs on the OS itself, with syntax highlighting, a build-and-run loop, an AI assistant, and UnoC, a built-in C compiler that compiles native UnoDOS apps on UnoDOS.

Python: MicroPython as a first-class runtime (PYRT.UNO) with a uno API into the shell, filesystem and network.

Music, UnoAmp, Photos: from-scratch WAV, MIDI, MP3 and AAC-LC decoders (unomedia); UnoAmp is a Winamp 2 clone that loads classic skins; Photos views the common image formats.

SSH: a native SSH client (ed25519, in-tree crypto).

Plus Files, Editor, Paint, Tracker, Clock, Control Panel, System, a log viewer, the games (Dostris, Pac-Man, OutLast) and Runner3D, the showcase for the uno3d 3D library.

Apps are loadable .UNO modules carrying their own descriptors: drop one into APPS\ and the shell discovers it. No rebuild, no reboot.

Everything below the firmware line is native, written for this tree:

unovirt enters VMX operation on Intel hardware and runs guests behind EPT with virtio devices: a real Ubuntu kernel boots under UnoDOS, reaches userspace, answers at its shell, and mounts an ext4 disk served from a file on a UnoDOS volume. The Appliances app and VM manager front it; an AMD/SVM backend is written and awaiting hardware proof.

Installer: non-destructive install onto an existing disk's ESP, or a whole-disk clone; a running machine can also be reinstalled over the network.

unosecure: local accounts, RBAC and an audit trail.

URC: a remote-control channel (fail-closed verb gate, one-time console arming) that drives real machines headlessly: deploying builds, running tests, streaming the screen. It is how the hardware fleet is validated without a human at the keyboard.

Debug builds: a behavioral spec (pc64/SPEC.md) executed as an on-metal conformance test, plus watchdogs, fault telemetry and a stress harness.

Proven on real machines

Validated on a Lenovo ThinkPad X1 Carbon Gen 8 (native trackpad, Wi-Fi, live theme and resolution switching), on an always-on ZimaBlade test box (boots from USB, detaches from the firmware, runs fully native), and on QEMU+OVMF harnesses that boot the real image on every change. The design notes in pc64/README.md record the firmware traps only real hardware exposes; they are half the value of the port.

sudo apt install gcc-mingw-w64-x86-64 qemu-system-x86 ovmf python3 python3-pil cd pc64 ./build.sh # -> build/esp/EFI/BOOT/BOOTX64.EFI ./build.sh run # boot it in QEMU+OVMF

The whole port builds with stock packages, no EDK2. See pc64/DEVELOPMENT.md for Linux and Windows environment setup and pc64/README.md for the full architecture tour.

One contract, many worlds

UnoDOS 3.1 is contract-driven: a single machine-readable Contract (unodef/) defines screen geometry, the window and event layout and the shared enums, and every world is generated from it or checked against it. The assembly ports and the x86 reference consume it byte-identically, and eleven ports were built fresh on the 3.1 architecture rather than migrated, proving that a new target costs a small generated surface. See docs/UNODOS-3.1-MIGRATION.md and docs/CONTRACT-ARCH.md.

Every port boots a UnoDOS desktop with the shared app set: Files, Notepad, Music, Theme, Tracker, Paint and the games (Dostris, OutLast, Pac-Man), scaled to what the machine can hold, down to a launcher profile on 2 KB of RAM. A feature-by-feature comparison lives in docs/FEATURE-MATRIX.md.

Several ports are validated on real silicon (NES, PC Engine, Genesis, Mac SE, the x86 line, pc64's laptop and SBC fleet); the rest are verified in emulators or on ROM-free instruction-level harnesses (Unicorn, py65, a from-scratch 65816 core), so no proprietary ROMs are needed to build or test anything.

The original UnoDOS 3: a GUI-first OS for IBM PC XT-compatibles, written entirely in real-mode x86 assembly. No DOS, no runtime, just the BIOS and an Intel 8088 or later.

sudo apt install nasm qemu-system-x86 make python3 make floppy144 # build/unodos-144.img, a bootable FAT12 floppy make run144 # boot it in QEMU

make hd-image builds the 64 MB FAT16 hard-drive image; tools/write.ps1 writes images to physical media on Windows (with system-drive exclusion and read-back verify), and plain dd does it on Linux.

Apps are flat NASM binaries in their own 64 KB segments; a minimal windowed app is about 60 lines. Start with the app development guide, the API reference (all 106 calls with register-level detail) and docs/ARCHITECTURE.md.

The ports stay small because the heavy machinery is shared:

master (this repo, hmofet/unodos): the forward, contract-driven line and the home of pc64. All current development happens here.

hmofet/unodos-3-legacy: the original shipped, real-hardware-validated OS and its ports (tag legacy-pre-3.1). Frozen and archived, known-good.

Documentation

User manual: install, desktop, apps, networking, appliances and the developer guide, for people who just want to run it.

docs/: architecture, API reference, port spec, feature matrix, storage and boot-chain internals, and the plan and handoff documents behind each subsystem.

CHANGELOG.md: the full history, 425+ builds and counting. Current version: v3.34.0.

AGENTS.md and CONTRIBUTING.md: how work lands in this tree.

License

Copyright (c) 2026 Arin Bakht

This project is licensed under the Mozilla Public License 2.0 (MPL 2.0).

Third-party components keep their own licenses and are unaffected by the above (MIT, Apache-2.0, BSD-3-Clause, public domain, and CC BY for two fonts). Every one of them is listed in THIRD-PARTY.md.

UnoDOS 3, because sometimes the old ways are the best ways.