Cosmos gen3: a bare-metal C# kernel framework built on NativeAOT

What Cosmos gen3 is for, and who should care

Cosmos is described as an operating system construction kit: you build your own OS using managed languages such as C#, VB.NET, and more. Gen3 is the branch that changes how that build works. The README states that it replaces the IL2CPU transpiler with the official .NET ahead-of-time compiler, so the result is an ordinary dotnet build that produces a bootable kernel ELF for x64 or ARM64, linked with an integrated runtime and packaged into an ISO with the Limine bootloader.

The audience is narrow and specific. Someone who wants to learn how a kernel boots and still write the scheduler, drivers and filesystem code in C# rather than in C or assembly. Someone teaching an OS course who wants students to read managed code. Someone who wants to experiment with the Cosmos plug system and the graphics, keyboard, mouse, network or filesystem subsystems the README lists, without first writing a bootloader and a page-table setup from scratch. It is not aimed at anyone shipping a device or a server.

NativeAOT replaces IL2CPU: what actually changes in the toolchain

Gen2 compiled C# IL to x86 assembly through IL2CPU, a custom transpiler with its own JIT-like backend maintained separately from the .NET ecosystem. The README is direct about the trade-off: IL2CPU is powerful, but it is a second backend that has to be kept in step with upstream .NET by hand. Gen3 removes that second backend. The same optimizer used in the wider .NET ecosystem now compiles the kernel, and new .NET features and new architectures arrive through the official toolchain instead of being reimplemented.

That is the whole architectural argument, and it has a cost the README does not dwell on. Anything that depended on IL2CPU's specific behaviour, including the way gen2 handled reflection or generic instantiation, is now the AOT compiler's problem. The README notes the work descends from Zarlo's NativeAOT patcher and points to issue 3088 for the design discussion, which is where the awkward cases would have been argued. The plug system and the runtime support are what make the AOT output bootable, and the repository layout reflects that: a nativeaot-patcher solution sits alongside the kernel source and its own test solution.

The runtime pieces listed are a mark-and-sweep garbage collector, a priority-based stride scheduler, exception handling, APIC interrupts on x64 and GIC on ARM64, ACPI through LAI, PCI and MMIO drivers, UART serial, AHCI/SATA and NVMe storage with MBR, GPT and EBR partitioning, and a FAT12/16/32 filesystem on a Unix-style VFS with mount, superblocks and inodes. That is a real kernel surface, not a demo that prints a string and halts.

Installing Cosmos gen3 and booting the DevKernel

The README does not give a step-by-step install. What it does give is the branch and the toolchain: gen3 is built with the .NET ahead-of-time compiler, and the repository ships a Makefile, a setup directory, a devcontainer and a global.json, which is where the SDK version is pinned. The Makefile is the entry point for building and running a kernel, and it defaults to x64 with the HelloWorld kernel.

The Makefile opens with the variables that control a build, and the architecture is one of them:

ARCH       ?= x64
TIMEOUT    ?= 30
KERNEL     ?= HelloWorld

OUTPUT     := ./output-$(ARCH)

Because OUTPUT is derived from ARCH, an x64 run writes to ./output-x64 and an ARM64 run to ./output-arm64. The ARM64 branch of the Makefile selects the linux-arm64 runtime identifier, defines ARCH_ARM64, and launches qemu-system-aarch64 with the virt machine, gic-version=3 and a cortex-a72, using an edk2-aarch64-code.fd firmware file from ~/.cosmos/tools/qemu:

QEMU         := qemu-system-aarch64 -M virt,gic-version=3 -cpu cortex-a72 -m 512M \
                  -bios ~/.cosmos/tools/qemu/share/qemu/edk2-aarch64-code.fd

The x64 branch selects linux-x64 and launches qemu-system-x86_64. The DevKernel target points at examples/DevKernel/DevKernel.csproj, and the test engine at tests/Cosmos.TestRunner.Engine/Cosmos.TestRunner.Engine.csproj.

The x64 QEMU flags are chosen at make time, not by you:

KVM_FLAGS    := $(shell test -w /dev/kvm && echo "-enable-kvm -cpu host" || echo "-cpu max")

If /dev/kvm is writable you get KVM and -cpu host; otherwise you get -cpu max under TCG. The comment above that line in the Makefile says TCG is roughly ten times slower and tanks guest FPS, and that -cpu host needs KVM. On a container or a CI runner without KVM, expect the slow path. The DevKernel run also uses -M q35, 512M of RAM, an ide-cd device for the ISO, -vga std, -device i8042 and -serial stdio, and the Makefile defines a readiness string, QEMU-DEVKERNEL-DEBUG-READY on x64 and QEMU-DEVKERNEL-ARM64-DEBUG-READY on ARM64, which is what a harness waits for before treating the boot as successful. A TIMEOUT variable defaults to 30 seconds.

There is also a docs target with DOCS_PORT defaulting to 8080, which serves the docs directory. The README's Documentation section splits that site into a User Guide for building your own OS and Contributor Docs for the architecture internals.

Where Cosmos gen3 will not help you

The largest limitation is stated by the project itself: gen2 is called the current public Cosmos OS, and gen3 is the next generation. The releases on this repository carry User Kit version numbers such as 3.0.88, but the README frames gen3 as the branch where the toolchain swap is happening. Anyone who needs the older, more widely used path should be looking at gen2, not this branch.

Second, the hardware story is QEMU-shaped. The Makefile's ARM64 path boots through edk2 firmware on the virt machine with a specific CPU model. Nothing in the README claims support for arbitrary physical machines, and the storage drivers listed (AHCI/SATA and NVMe) are the ones a virtual machine exposes. If your goal is to boot on a laptop you own, that is an untested path as far as this material goes.

Third, the documentation is split across a separate site and the repository's docs directory, and the README does not document rollback, a supported upgrade procedure between User Kit versions, or what happens to a kernel when the underlying AOT toolchain moves. The release cadence visible here is tight, three User Kit builds within a week, and each one is a new compiler output for your kernel. Treat that as a moving target rather than a pinned platform.

Cosmos gen3 compared with writing a kernel in C

The obvious alternative is the traditional route: C or C++ with a linker script and a bootloader such as Limine, GRUB or Multiboot. The difference is not the bootloader, since gen3 uses Limine too. It is the language runtime. In C you write your own allocator, your own exception story (usually none), and you manage every pointer yourself. In gen3 the README lists a mark-and-sweep garbage collector, exception handling, and a priority-based stride scheduler as part of the framework, so those are things you configure or extend rather than build.

That convenience is also the constraint. With a C kernel your build is a compiler and a linker, and you can reason about the exact instructions emitted. With gen3 your build is the .NET AOT toolchain plus the Cosmos plug system plus the nativeaot-patcher, and the boundary between your code and the runtime is where the interesting bugs live. A second alternative is a unikernel or a library OS that runs managed code on top of an existing hypervisor rather than on bare metal; gen3's selling point is precisely that it does not do that, since the README describes a bootable kernel ELF linked with an integrated runtime and packaged into an ISO. If you want the managed-language ergonomics without owning the hardware, that route is cheaper. If the point of the exercise is the hardware, gen3 is the one that keeps you on it.

Licence and the cost of tracking User Kit releases

Cosmos gen3 is BSD 3-Clause, described in the README as the original Cosmos license, with copyright 2007-2026 held by CosmosOS, the COSMOS Project. That is a permissive licence, and it is the same one gen2 used, so a kernel built on gen3 inherits the same terms. The practical question for anyone embedding this in a product is not the licence text but the third-party components the README names: Limine for boot, LAI for ACPI, and the nativeaot-patcher that gen3 is based on. Each of those carries its own licence, and the README does not spell them out. Check the LICENSE file and the submodule contents before you ship anything. This is a description of what the repository states, not legal advice.

The upgrade cost is the part worth weighing. Three User Kit releases landed between 2026-09-17 and 2026-09-21, and the last push to the repository was on 2026-09-23. A fast cadence is good for fixes and bad for anyone who wants a frozen compiler. Because gen3's output depends on the .NET AOT toolchain, a User Kit bump can change the generated code for your kernel even when you changed nothing. The README does not describe a migration guide between User Kit versions, so plan to rebuild and re-run the kernel test suite after each bump rather than assuming compatibility.

Editorial conclusion

Adopt Cosmos gen3 if you want to write kernel code in C# and are willing to build from the gen3 branch, where the Makefile drives QEMU for x64 and ARM64. Do not adopt it if you need a production OS, a stable API surface, or a release you can pull without building the repository. Before committing, verify that your machine can run QEMU with KVM, since the Makefile falls back to TCG when /dev/kvm is not writable and the comment in that file puts TCG at roughly ten times slower.

Frequently asked questions

Official sources

1. CosmosOS/Cosmos on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases