ToaruOS: a from-scratch operating system you build in a Docker container

An operating system with no third-party runtime dependencies

Most hobby kernels stop at a scheduler and a shell. ToaruOS ships a full stack: the Misaka kernel, a C standard library with a dynamic linker, the Yutani window compositor, a terminal emulator, a Vim-inspired editor called Bim, and Kuroko, a dynamic bytecode-compiled programming language. The README describes the project as "complete, independent" and states that all of it is original to the project with no third-party dependencies. That is the actual selling point. If you want to study how a window compositor talks to a kernel without X11 or Wayland in between, or how a libc implements dlopen from scratch, this repository contains the whole chain rather than a shim over existing components.

The intended audience is narrow but real. It suits people who read kernel source for pleasure, students working through OS design, and developers who want to port software to a small POSIX-like target. Development started in January 2011, the first full release came in 2017, and the kernel was rewritten and ported to x86-64 with SMP support for the 2.0 release in December 2021. An aarch64 port followed in early 2022. That history matters because it tells you the codebase has survived a full kernel replacement, which is not a small thing for a project of this size.

Misaka, Yutani and a build that generates its own Makefiles

The architecture is visible in the repository layout. kernel/ holds Misaka, described in the README as a hybrid modular kernel. modules/ holds loadable driver modules, and the root Makefile comments that one file equals one module, with `ld -r` suggested if you ever need a multi-object module. apps/ contains userspace applications, all first-party, and libc/ contains both the C standard library and the dynamic linker at libc/dlfcn/dl.c. lib/ holds userspace libraries, and base/ is the ramdisk root filesystem staging directory, including headers under base/usr/include and graphical resources for the compositor and window decorator.

The build is the part that surprises people. The Makefile uses a Kuroko tool, auto-dep.krk, to generate additional Makefiles for userspace applications and libraries, resolving dependencies from `#include` directives rather than from hand-written lists. The README says the C library, kernel, userspace libraries and applications are then built in an indeterminate order, combined into a compressed archive used as a ramdisk, and packaged into an ISO9660 image. Indeterminate order is the project's own wording. In practice that means the build graph is discovered, not declared, so a stale .make/ directory is a plausible source of confusing failures. The generated Makefiles land in .make/, which is a top-level entry in the repository.

Building ToaruOS in Docker and booting it in QEMU

The README recommends that general users fork the repository and let the GitHub CI pipeline do the work. Local builds are supported on an appropriately configured Linux host with Docker, using the project's build container with the repository bind-mounted at /root/misaka. The submodules must be initialized first, because kuroko and bim are submodule checkouts rather than vendored directories.

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

The container runs util/build-in-docker.sh with the working directory set to the bind mount, so the artifacts appear in your checkout rather than inside the container. LANG is set to C.UTF-8, which matters for a build that processes text with tools expecting a UTF-8 locale. Expect the first run to take a while: a cross toolchain is staged into util/ and then the kernel, libc, libraries and applications are compiled.

Once that finishes, the Makefile exposes utility targets. The README points at `make run` and mentions `make shell` for running a ToaruOS shell over a serial port with QEMU. The Makefile sets `EMU = qemu-system-${ARCH}` and derives ARCH from util/arch.sh unless you override it, so the same targets work for the x86-64 and aarch64 ports.

make run
make shell

For a graphical session, the README says the best end-user experience is in VirtualBox or VMware Workstation, because ToaruOS supports their automatic display sizing and absolute mouse positioning. Set up an "other" 64-bit guest, give it at least 1GiB of RAM, attach the CD image, remove or ignore any hard disks, and select an Intel Gigabit NIC. Two or more CPUs are recommended. One detail worth knowing before you file a bug: the bootloader passes a flag to the VirtualBox driver that disables Seamless support by default because the README states the implementation has a performance overhead. The bootloader menu has an option to turn it back on.

The C library is the weak point, and the README says so

The project's own goals section is unusually candid. Improving POSIX coverage, especially new utilities and more correct file system behavior, is listed as in progress. So is continuing to improve the C library, which the README states "remains quite incomplete." A third goal is replacing third-party development tools to reach a state where the OS is self-hosting with just the addition of a C compiler.

Read those three together and you have the practical limit. This is not a system where you can expect an arbitrary autotools project to configure and build. The root filesystem layout reflects the gap: /usr/bin is described as holding third-party applications that are normally empty until packages are installed, and /usr/lib is expected to contain libgcc_s.so by default. The package manager manifest cache lives in /var. So there is a package mechanism, but the default image is first-party software plus whatever you add.

A second limitation is hardware. ToaruOS targets x86-64 PCs and ARMv8 VM environments. The README frames ARMv8 support in terms of virtual machines, not boards, and the recommended end-user path is VirtualBox or VMware. If you want to run this on physical hardware, you are on your own in a way the documentation does not walk you through. The README also does not document rollback or recovery if an upgrade breaks the system, and it does not describe the package manager's command syntax in the sections available here.

ToaruOS next to SerenityOS, Redox and the hobby-OS field

The obvious comparison is SerenityOS, which people search for alongside ToaruOS. Both are from-scratch systems with their own kernel, libc and graphical stack, and both are written largely by a small group with a strong aesthetic. The difference is in the surrounding ecosystem and the language bet. SerenityOS has built out a large userspace and its own JavaScript engine, and it has attracted a broad contributor base. ToaruOS is smaller and more tightly scoped, and its scripting language, Kuroko, is a separate project with its own repository and documentation site. If you want a from-scratch OS with a large body of existing applications to study, SerenityOS has more surface. If you want something you can hold in your head, ToaruOS is the smaller read.

Redox OS takes a different architectural route entirely: a microkernel design in Rust, where drivers and filesystem servers run as userspace processes. ToaruOS's Misaka is described as a hybrid modular kernel, which sits between monolithic and microkernel designs and keeps drivers as loadable modules inside the kernel address space. That choice makes the driver model simpler to follow but means a faulty driver has more room to take the system down.

ReactOS is the other name that comes up, and it is solving a different problem: binary compatibility with Windows. ToaruOS has no compatibility goal of that kind. It is its own system with its own conventions, and that is the point. If what you actually need is to run existing software, none of these from-scratch systems is the right answer, and the search results that pair ToaruOS with ReactOS are misleading.

Licence, releases and what an upgrade costs you

ToaruOS is released under the NCSA licence, a permissive, MIT-style licence. For anyone embedding code from the kernel, libc or userspace into another project, that is the permissive end of the spectrum, but the usual caveat applies: read LICENSE in the repository root and the headers of the specific files you copy, because a project this size can carry file-level notices that differ from the top-level licence. Nothing here is legal advice.

On maintenance, the repository is not archived and the last push was on 2026-09-21, so the tree is being touched. Releases are tagged, with v2.3.0 on 2026-04-27, v2.3.1 on 2026-05-04 and v2.3.2 on 2026-05-12. Those three tags land within about two weeks of each other, which suggests a patch cadence rather than a long release train. The README does not document an upgrade path between releases, so treat a version bump as a rebuild from source rather than an in-place update.

That is the real cost of following this project. You are not pulling a package and restarting a service. You are re-running the Docker build, regenerating the ramdisk and ISO, and rebooting the VM. The kernel defines KERNEL_GIT_TAG from util/make-version at compile time, so the version string baked into a build comes from your checkout, not from a release artifact. Budget for a full rebuild whenever you move between tags, and keep the working .make/ directory out of version control so generated Makefiles do not confuse the next build.

Editorial conclusion

Adopt ToaruOS if you want to read or modify an operating system that owes nothing to Linux, and if you are comfortable building inside the project's Docker image and booting the result in QEMU, VirtualBox or VMware. Do not adopt it as a desktop or server OS: the README states the C library remains quite incomplete, POSIX coverage is still being improved, and the project is not yet self-hosting without a C compiler. Before committing, check the current release tags, confirm the build-tools image tag you intend to pull, and read util/build-in-docker.sh so you know what the container actually builds.

Frequently asked questions

Official sources

1. klange/toaruos on GitHub
2. License: NCSA
3. Project website
4. README
5. Releases