osakaOS: a hobby 32-bit operating system written to feel like demo software

A demo scene operating system, on purpose

osakaOS is described as a 32-bit, optionally multitasking, megalithic operating system made with a focus on unconventional or ridiculous design choices. The stated intent is to emulate the experience of a videogame or demo software rather than a traditional desktop operating system.

That framing is the most useful sentence in the readme, because it tells you how to judge the project. This is not an attempt at a usable Linux replacement. It is an exercise in writing an operating system end to end, with the aesthetics of a 90s demo scene, and the author is explicit about the origin of the idea.

The readme includes a question and an answer that explain the whole project. Why did you make an entire OS after this character, are you obsessed or something. No, I just thought it would be funny. The character in question is Ayumu Kasuga, and the homepage points at the author's YouTube channel, where the project received, and will receive, monthly updates during development.

So the audience is people learning operating systems and people who enjoy watching one get built. The project is partly based on the WYOOS tutorial series, although the readme notes that many things from the tutorial have been changed or removed for various reasons. That last clause matters, because a tutorial-derived codebase is where the interesting parts have been rewritten and the parts left alone are the ones being learned.

Two user-facing systems: the Osaka FileSystem and AyumuScript

osakaOS has its own file system, the Osaka FileSystem, and its own scripting language, AyumuScript, and the command list in the readme is the API documentation for both.

The filesystem commands are simple: `files` lists all known files and the number currently allocated, `tag` assigns an organisational tag to a file, `size` prints the size in bytes, and `delete` removes a file. The tag concept is unusual for a filesystem and is a good example of the design choices the project is making deliberately.

AyumuScript is the programming side. `var` defines a variable with a name and a type, `=` computes an arithmetic expression and stores it, `if/loop` tests an expression and, if it is not true, the commands are not processed, and `fi/pool` allows a command to be processed again. There is `putpixel` to draw a pixel with a given colour, `window` to create a user window for graphical programming, `drawpic` to fill an image buffer onto a graphical target, and `//` for comments. Two commands run other files: `ex` executes a file as a script in single tasking mode, and `ext` executes a file in multitasking mode.

The generic commands are `say` to print arguments, `help` to list common commands and keyboard shortcuts, and `clear` to clear the screen. Then there is the system and driver layer, which is the most striking part of the list: `delay` uses the PIT timer to delay the system by a number of milliseconds, `beep` uses the PC speaker, `rmem` reads a value from a memory address, `wmem` writes a value to a memory address, `rdisk` reads from a sector, and `wdisk` writes data to a sector.

Those five are the point of the project. A shell that can read and write raw memory and raw disk is not a general purpose interface, and a visitor who finds the `wdisk` command has understood osakaOS faster than any documentation would have told them.

The Makefile is the system map

The build is a plain Makefile, and its object list is the clearest description of the operating system available anywhere in the repository.

The compile flags tell you the constraints. The C++ parameters include `-m32` and `-nostdlib`, plus `-fno-pie`, `-fno-stack-protector`, `-fno-builtin`, `-fno-rtti`, `-fno-exceptions`, `-fno-threadsafe-statics` and `-fno-leading-underscore`, and the assembler parameters are `--32`, and the linker parameters are `-melf_i386`. A freestanding 32-bit kernel linked without the C library, with no exceptions and no RTTI, is a serious constraint set and it explains the size of the code.

The object list then walks the system in order. The core is `gdt.o`, `memorymanagement.o`, `art.o` for the allocator, `multitasking.o`, `kernel.o`, `loader.o` and `script.o`. Hardware communication is a directory of its own: `port.o`, `interrupts.o`, `interruptstubs.o` and `pci.o`. The drivers cover `keyboard`, `mouse`, `vga`, `ata`, `pit`, `cmos`, `speaker`, `ac97` for audio and `amd_am79c973` for the network card.

Then the parts a user would notice. The `gui/` directory has `widget.o`, `desktop.o`, `window.o`, `sim.o` and `raycasting.o`, plus `gui/games/platformer.o` and `gui/games/shooter.o`, which tells you the desktop has platformer and shooter games in it. The `net/` directory has `network.o`, `etherframe.o`, `arp.o`, `ipv4.o`, `icmp.o`, `udp.o` and `tcp.o`. The `filesys/ofs.o` is the Osaka FileSystem. The `app/` directory holds `paint.o`, `browser.o`, `file_edit.o` and `file_browse.o`, so there is a paint program and a browser. The `mode/` directory has `piano.o`, `snake.o`, `file_edit.o` and `space.o`.

A stack of games, a paint program, a browser and a raw memory shell, all in one tree with a 32-bit freestanding kernel underneath. That is the project.

Building and running it under QEMU

There is a pre-compiled bootable ISO image in the repository, `osakaOS.iso`, that you can use in any normal virtualization software. To compile from source, the instruction is short.

sudo make run

The binary is built and QEMU boots from the virtual disk. The packages you will probably need are listed too:

sudo apt-get install g++ binutils libc6-dev-i386 qemu-system-x86_64 grub-legacy grub2 xorriso

If you plan to use other emulators, the readme lists the requirements: piix4 IDE support for storage, at least 16MB of memory, standard VGA emulation, and PC speaker support for basic audio.

The audio setup on a Linux host with PulseAudio needs one line added to `/etc/pulse/default.pa`:

load-module module-native-protocol-unix auth-anonymous=1 socket=/tmp/pulse-socket

and then PulseAudio is restarted so the settings in the makefile work.

The advice about other emulators is followed by the most important paragraph in the readme. Emulation is the preferred way to run the OS, because running it on real hardware requires a very old machine for the drivers to work, and because of a lack of concern for the data on the machine, since the OS does not care to ask whether you want to write over a pre-existing system partition, it will just do it. There is also a lack of error catching that can cause crashes.

That paragraph is the project's own risk assessment, and it is unusually candid for a hobby OS.

Where osakaOS is the wrong tool

Four limits are clear, and the project states most of them itself.

The first is reliability. The readme notes a lack of error catching that can cause crashes, and the bug list is specific: window input for scripts being janky, paint width being difficult, small GUI errors when drawing programs, and other things too long to list. This is a system where a mistake in a script can take the machine down, and where a mistake at the disk level overwrites a partition.

The second is completeness. The network stack is the obvious gap. The readme says that for the next major update the plan is to further build the network stack and implement internet functionality, along with more advanced graphical applications and custom media encodings. The presence of `arp.o`, `ipv4.o`, `icmp.o`, `udp.o` and `tcp.o` in the build shows how far the design goes, but the roadmap statement is the honest summary of where it stands.

The third is the delivery model. There are no GitHub releases, the project is updated on a YouTube channel during development, and the last push to the repository was on 2026-05-03. So there is no versioned artefact to download, only a branch to clone, and the monthly update cadence is a video series rather than a changelog.

The fourth is that none of this matters for the use the project is actually for. A system with a raycasting GUI, platformer and shooter games, a paint program, a browser and a scriptable shell is not competing with anything. It is a learning artefact and a piece of performance art, and evaluating it against the criteria you would use for a real operating system is the wrong frame. The licence is GPL-3.0, and for reading, building and extending it that is simply the most permissive choice available.

The desktop, and what it is for

A word about the visual side, because it is the part that makes osakaOS look different from the tutorial series it came from.

The readme shows a desktop screenshot and explains that the desktop is entered by pressing the windows or command key. The screenshot directory in the repository carries files like `desktop13H.png`, and there is an animated `cube.gif` and a `room.png`.

The `gui/` tree explains what is happening underneath. There is a widget layer, a desktop, a window manager of sorts, a `sim.o` and a `raycasting.o`, which is how the visuals are produced, and the two games live in `gui/games/`. The `mode/` directory holds the text-mode equivalents, with `piano.o`, `snake.o`, `file_edit.o` and `space.o`, and the readme's opening sentence says the system uses different text modes and graphical programs to edit files using the Osaka FileSystem and create programs using AyumuScript.

So there are two parallel environments, a text mode with its own classics and a graphical mode with a raycasting desktop, and the same file system and the same scripting language underneath both. The `tag` command in the filesystem and the `window` and `drawpic` commands in the script language are the parts that hint at the design being coherent rather than a pile of features.

The repository root also has two small conversion tools, `OFS_File_To_Image.cc` and `OFS_Image_To_Disk.cc`, which move data between the Osaka FileSystem and disk images, and a `linker.ld` for the kernel link. Those two tool names are a compact description of the storage design: a filesystem that is a file on a disk image, with tools to read and write it.

Editorial conclusion

osakaOS fits a learner who wants to read a complete operating system, from the GDT and memory management through drivers, a shell and a GUI, in one readable tree, and it fits someone who wants to experiment with a graphical environment that is not a browser. It does not fit anything that needs to be reliable, and the readme says so itself, warning about the lack of error catching and the fact that it will overwrite a pre-existing system partition without asking. Before you spend time on it, build and run it under QEMU with the bundled ISO, and read the command list, since the shell exposes raw memory and disk access through `rmem`, `wmem`, `rdisk` and `wdisk`.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. pac-ac/osakaOS on GitHub
4. Project website
5. README