Noureddine RAMDI / ToaruOS: A self-hosted hobby operating system built from scratch

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
927 Words
github-stars operating-system c hobby-os kernel self-hosted

klange/toaruos

ToaruOS is a distinctive project in the world of hobbyist operating systems because it aims to build everything from the ground up — kernel, C library, dynamic linker, windowing system, and even its own bytecode-compiled language — without relying on third-party runtime dependencies. Over more than a decade, it evolved from an educational playground into a self-hosting OS with a modular hybrid kernel and a complete userspace stack. This level of self-containment is rare, especially given the complexity involved in OS development.

What ToaruOS is and how its architecture is organized

At its core, ToaruOS is a hobby operating system targeting x86-64 and ARMv8 architectures. The project started as a learning resource and is not primarily experimental or aimed at commercial use. It presents a comprehensive OS stack:

  • The Misaka hybrid modular kernel, fully rewritten in 2021 to replace an older design that the author regarded as a technical debt.
  • A custom C standard library implementation designed to replace Newlib, removing external dependencies.
  • A dynamic ELF linker/loader (ld.so) to support shared libraries.
  • The Yutani composited windowing system, handling graphics and user interface composition.
  • Bim, a Vim-inspired syntax-highlighting editor written for the OS.
  • Kuroko, a bytecode-compiled programming language developed within the ecosystem.

The codebase is approximately 100k lines of C with no external runtime dependencies, reflecting a commitment to self-hosting. The project layout is well organized, with separate directories for kernel, userspace libraries, applications, the C library, and build scripts. This modular structure supports building components independently and integrating them into a bootable ISO image.

The technical strengths and design tradeoffs of ToaruOS

What sets ToaruOS apart is its zero-dependency philosophy. Early versions relied on third-party libraries like Newlib, Cairo, and Freetype. However, the 1.6 release marked a critical milestone by shedding all these dependencies. This means every piece of the OS stack, from kernel to UI, is developed in-house.

The 2021 kernel rewrite is a key technical highlight. The original kernel was a decade old and considered by the author to be an embarrassment, reflecting common architectural debt in long-running hobbyist projects. The Misaka kernel rewrite introduced a hybrid modular design, improving maintainability and laying the groundwork for features like better SMP scheduling and a rewritten network stack.

The build system also deserves mention. It uses a Kuroko script (auto-dep.krk) to parse #include directives and automatically generate Makefiles, streamlining dependency management for userspace libraries and applications. This approach improves developer experience (DX) while maintaining the project’s commitment to minimal external tooling.

Tradeoffs are clear: the project prioritizes educational clarity and self-hosting over raw performance or extensive hardware support. The OS currently focuses on expanding POSIX compliance and improving SMP capabilities, but it’s not designed for production workloads. The custom C library and dynamic linker reflect significant engineering effort but may lack the maturity and optimizations found in widely used libraries.

Building and running ToaruOS from source

The repository provides a Docker-based build environment to simplify compilation on Linux hosts. The recommended approach is to clone the repository, update submodules, pull the official build tools Docker image, and run the provided build script inside the container. Here is the exact sequence of commands as per the official README:

git clone https://github.com/klange/toaruos
cd toaruos
git submodule update --init kuroko
git submodule update --init bim
docker pull toaruos/build-tools:1.99.x
docker run -v `pwd`:/root/misaka -w /root/misaka -e LANG=C.UTF-8 -t toaruos/build-tools:1.99.x util/build-in-docker.sh

After building, you can run various utility targets such as make run to launch the OS in QEMU or make shell to open a ToaruOS shell over a serial port.

The build process combines the kernel, userspace libraries, and applications into a compressed ramdisk archive, which is then packaged into an ISO9660 filesystem for booting. This pipeline reflects a typical but well-integrated hobby OS workflow.

Verdict

ToaruOS is a compelling project for systems programmers and OS hobbyists who want to explore a fully self-hosted operating system built from scratch. Its long evolution and willingness to rewrite large components like the kernel publicly provide valuable learning material.

The zero-dependency model is ambitious and educational, but it comes with tradeoffs in terms of hardware support, performance, and ecosystem maturity. It’s not a choice for production use but rather a reference and exploration platform.

If you want to understand how an OS is built end-to-end — including kernel design, dynamic linking, windowing, and even language runtime development — ToaruOS is worth examining. The Docker-based build setup lowers the barrier to experimenting with the codebase.

Overall, ToaruOS is a hands-on educational resource that balances architectural evolution with practical self-hosting goals, making it a unique and honest project in the hobby OS landscape.

→ GitHub Repo: klange/toaruos ⭐ 6,754 · C