KolibriOS and the operating system written in FASM assembly

An operating system in assembly, deliberately

KolibriOS is described in the README as a hobby operating system for x86-compatible computers, currently being developed by a small but passionate team of enthusiasts.

The defining technical decision is stated in the next sentence. Its kernel, most drivers, and many programs are written entirely in FASM assembly language, making them very compact and lean on system resources. That is the whole architectural premise in one line. A system whose kernel is in assembly has no runtime, no garbage collector, no loader for a managed runtime, and no compiler in the boot path, so the entire resident footprint of the system is bounded by the size of the code and whatever the drivers allocate.

The other half of the design is inherited rather than chosen. KolibriOS is based on MenuetOS, and the README is explicit that it uses its own standards and is NOT fully POSIX or UNIX compliant. The project also preserves all MenuetOS copyrights and gives special thanks to its author, Ville Turjanmaa, for the 32-bit original.

That lineage explains a lot about the shape of the system. MenuetOS was a 32-bit assembly-first operating system with a graphical interface, and KolibriOS extends that tradition rather than replacing it. A reader looking for a Unix-like system with a POSIX syscall layer will not find one here.

The audience is a systems programmer or a hobbyist who wants to understand a complete operating system, and the second audience is anyone who wants a fast, tiny desktop to run on old hardware.

The source tree tells you what the system is made of

The repository root is a map of the operating system, and the directory names are the architecture.

There is a kernel/ directory, a drivers/ directory, a programs/ directory, and a skins/ directory for the graphical interface. A data/ directory holds the assets, and a contrib/ directory holds contributed code. The _tools/ directory holds the tooling used to build and maintain the system.

The split between kernel, drivers and programs is the conventional one, but the proportions are what differ from a Linux or a BSD tree. This is a system where the driver layer is written by the same people as the kernel in the same language, so the interface between them is not a stable ABI negotiated between independent projects. That is what buys the compactness, and it is also why the driver set is tied to the hardware the team has.

The skins/ directory is worth pausing on. A graphical desktop in an assembly-written operating system means the window manager, the widget drawing and the theme system are all in the same low-level world, and the theme is a data format rather than a set of images the compositor knows how to interpret. For a hobby OS, that is a deliberate and unusual investment.

The contrib/ directory is the counterpart: third-party code that does not have to meet the kernel's constraints, and it is where the boundary between the hobby core and the wider world is drawn.

The build system is Tup, and it is part of the design

The build configuration lives in files with revealing names. There is a Tuprules.lua at the repository root and a tup.config.template, plus a build.txt and a shell.nix.

Tup is a Linux-native build system driven by a Lua configuration, and the fact that the project uses one is not a neutral detail. A Tup build computes a dependency graph over its inputs, so a change to a source file rebuilds only what depends on it, and the whole tree can be rebuilt incrementally. For a system where the kernel and the drivers are interdependent assembly modules, a build system that understands the dependency graph precisely is worth more than it would be in a project with a conventional compiler driver.

The shell.nix means the build environment is pinned rather than whatever happens to be installed, which for a hobby OS built by a small team across different machines is a practical necessity rather than a nicety. The tup.config.template is a template, so a new contributor copies it and fills in their own settings instead of editing a shared file, which is the pattern that keeps local configuration out of version control.

The README also carries a build system badge pointing at the project's own CI, at git.kolibrios.org, and the .gitea/ directory at the repository root shows the CI is Gitea Actions, running on the project's own server rather than on a hosted forge.

This repository is a mirror, and that changes where you contribute

The repository description says it plainly: this is the official mirror of the main KolibriOS repository.

That distinction has practical consequences and they are worth stating before anyone clones and starts work. The homepage in the metadata points at git.kolibrios.org, and the build badge, the issue link and the contribution guide all point there as well. The issues page referenced in the README is on the project's own host, and the contribution guide link in the README is a relative path, which suggests the guide lives alongside the real source.

So a pull request opened here is not necessarily where it will be reviewed, and an issue filed here may not be seen. The README's contributing section asks for participation and points to the contribution guide for the details of the process, and it points separately at the issues page on the main repository for the common list of tasks, issues and enhancement proposals.

The mirror still has value. It is on GitHub, so it is reachable by tooling that only knows about GitHub, and it is a fast way to read history or grep across the tree without adding the project's own host to your toolchain. But for a first contribution, the project's own server is where the work is reviewed.

Note also that the licence is stated in the README as GPL-2.0 with the badge pointing at COPYING.TXT, and the project is not a fork of anything modern: it is a descendant of a 32-bit assembly system, and the code in the tree is the assembly kernel, drivers, programs and tooling rather than a layered userspace.

What the README does not tell you, and what that means

The documentation here is deliberately short, and for a project of this scope that is both honest and limiting.

There is no build walkthrough in the README. It points to the official KolibriOS website for more information, downloads and documentation, and to the contribution guide for the contribution process. There is no description of the supported hardware, no list of the drivers, no syscall documentation and no statement of which compiler or assembler versions are supported, even though the whole system is built with FASM.

That means an evaluation of KolibriOS cannot be completed from this repository alone. The questions you actually need answered, what hardware it runs on, whether it has a network stack, what the filesystem looks like, are all in the documentation on the website or in the source itself.

The repository layout also tells you the development language situation. The primary language is listed as C, but that is almost certainly the tooling and the contributed C code, since the README says the kernel, most drivers and many programs are in FASM assembly. The topics list confirms it, with assembler, assembly and fasm among them, alongside kernel, os and osdev. So the C is real but it is not the system.

The one structural fact that follows from the assembly choice deserves emphasis. Because the system is written in assembly against x86-compatible hardware, it is tied to that architecture in a way that a C kernel with a portable HAL is not. That is what makes it fast and small on old machines, and it is also what makes it a curiosity rather than a deployment target for most teams.

Editorial conclusion

KolibriOS is a good fit for a systems programmer who wants to read a complete operating system, kernel and drivers included, because the whole system is small, the source is in one repository and the code is written in a language that hides nothing from the reader. It is a poor fit as a production operating system, since the project describes itself as a hobby system developed by a small team of enthusiasts, and a poor fit if you need POSIX compatibility, which the README says it does not provide. Before building, read the contribution guide and the build instructions on the official site, and note that this GitHub repository is a mirror, so issues and pull requests belong on the project's own git host rather than here.

Frequently asked questions

Official sources

1. Issues
2. KolibriOS/kolibrios on GitHub
3. License: GPL-2.0
4. Project website
5. README