# mycelium: a WebAssembly operating system that still prints hello world

> A Rust research project aiming at a microkernel-ish OS that runs WebAssembly modules in kernel and user space with WASI as the syscall layer, currently booting one hello world module under QEMU, and shipping the bare-metal Rust libraries it needed along the way.

**hawkw/mycelium** — 🍄  an alleged 'operating system'

- Repository: https://github.com/hawkw/mycelium
- Website: https://mycelium.elizas.website
- Stars: 804 · Forks: 35
- Language: Rust
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/hawkw-mycelium

## The kernel runs one module, and the project says so plainly

The project notes are unusually direct about the current state, and that honesty is the first thing to read.

The description calls it an alleged operating system. The headline under the title says that someday this will do stuff. And then it explains the situation without euphemism: right now Mycelium runs one WebAssembly module, which prints hello world and immediately exits, and the project adds that so that's coming along great, thanks for asking.

The aspiration is spelled out further down. The repository contains Mycelium, an alleged operating system, and a collection of Rust libraries written as part of its development. Eventually Mycelium will be a microkernel-ish operating system that runs on commodity desktop hardware, executes WebAssembly modules in both kernel and user space, and implements the WebAssembly System Interface, WASI, as its syscall layer.

That is a coherent and interesting target. A microkernel with WASI as the syscall interface means the boundary between kernel and user space is a WebAssembly ABI rather than a Linux syscall ABI, which means modules can be written in any language with a WASI toolchain and moved between kernels that implement the same interface.

The current state, though, is a research project in its opening stage. The primary package in Cargo.toml is `mycelium-kernel` at version 0.0.1, and the repository is not archived, with the last push on 2026-08-07.

## The libraries are the real deliverable

The project notes frame the whole repository with a question: what if the real operating system was the libraries we wrote along the way?

That framing is the honest one, because the crates in the tree are more usable than the kernel is.

`cordyceps` is a library of intrusive data structures, including linked lists and lock-free MPSC queues, with the documentation linking to the Boost documentation on intrusive containers for the concept. `maitake` is described as an async runtime construction kit for using Rust's async and await in bare metal applications such as operating systems. `mycelium-alloc` is a buddy-block memory allocator. `mycelium-bitfield` is a bitfield library built on const evaluation and declarative macros. `mycelium-util` is a standard library of reusable components for bare-metal no_std Rust projects, such as no_std synchronisation primitives.

The project notes say some of these may be generally useful for other projects, and that they have been or will be published to crates.io. The release tags confirm it for at least one: maitake-sync v0.2.2, v0.1.2 and v0.1.1 are the tagged releases in the list, all from the maitake-sync crate rather than from the kernel.

For a Rust developer doing embedded or no_std work, maitake in particular is the interesting one. An async runtime construction kit for bare metal is a genuine gap in the ecosystem, and this is a case where the side effect of a research project is the product.

## Hardware abstraction and the components around the kernel

Beyond the general purpose crates, the repository holds the Mycelium specific components.

`hal-core` holds the core interface definitions of Mycelium's hardware abstraction layer, which the README describes with the phrase admittedly somewhat half-baked. `hal-x86_64` implements that HAL for 64-bit x86 CPUs. The top level also carries `hal-multiboot2`, a directory not mentioned in the crates list but visible in the repository layout, and a `pci/` crate that appears in the Cargo.toml as `mycelium-pci` with a path dependency.

`mycotest` provides testing utilities for Mycelium's in-kernel tests, and `inoculate` is Mycelium's build tool, named in the README as the Horrible Build Tool, with the trademark symbol and all.

The `trace/` directory backs the `mycelium-trace` crate, and the workspace members list in Cargo.toml is the full list of what gets built together: alloc, bitfield, cordyceps, util, hal-core, hal-x86_64, inoculate, maitake, maitake-sync, mycotest, trace and pci, with resolver set to 2.

The root package pulls in the interesting dependencies for a kernel: `acpi` for power management, `bootloader_api` for the bootloader, `embedded-graphics` for output, `rand_xoshiro` and `rand` for randomness, `rlibc` for the C library interface, `pc-keyboard` for input, `thingbuf` for a buffer type, and `futures-util` with async-await features for the async runtime. The build profile sets `opt-level = 3` even in dev, which tells you the project treats debug builds as unusably slow for the kernel.

## Building it: one command through a custom build tool

The build is the clearest part of the project and the part you can actually run today.

To launch Mycelium in QEMU, the README says to run:

```console
cargo run-x64
```

That single command goes through inoculate, the Horrible Build Tool, which handles the build and the emulator launch. The emulator named is QEMU, and the simplest way to run the kernel is the one the project documents.

The environment setup details are deliberately pointed at CONTRIBUTING.md rather than duplicated in the README. The repository top level shows what is needed: a `rust-toolchain.toml` pinning the Rust toolchain, a `.cargo/` directory with cargo configuration, a `default.nix` and `shell.nix` for a Nix development shell, a `.envrc` for direnv, and a `justfile` for task running.

The justfile is worth a look because it shows the testing strategy. The `test` recipe runs host tests, loom tests and miri tests, and doc tests. The loom crate is set to `-p cordyceps -p mycelium-util`, meaning those two crates are the ones checked under the loom concurrency model checker. The `miri` recipe targets the same two crates for undefined behaviour detection. There is also a `no-nextest` switch to disable cargo nextest, and a `toolchain` variable that overrides the default set in rust-toolchain.toml.

## Reproducible toolchains, because a kernel is sensitive to its host

Several files in the repository exist for one reason: to make the build reproducible on a machine you did not choose.

The `rust-toolchain.toml` pins the compiler, and the justfile has a `toolchain` override that lets you switch away from that pin, with the `_cargo` variable expanding to `cargo` plus the override. The `.envrc` and the two Nix files, `default.nix` and `shell.nix`, give you a development environment with the right tools in it, which matters for a project whose test matrix spans a normal host build, loom, miri and in-kernel tests.

The `netlify.toml` and the Netlify badge for the documentation site indicate that the docs are built and published automatically from the main branch.

The `cliff.toml` file is worth noting for a different reason. cliff is a tool for generating changelogs from commit history, and having it configured in the repository means the release notes are derived from commit messages rather than written by hand. That is a reasonable choice for a project where the kernel itself changes rarely but the crates underneath it change often.

The `x86_64-mycelium.json` file at the top level is the machine description for the target, and `pci/` and `hal-multiboot2/` sit alongside it as the pieces that read hardware on that machine.

None of this is exotic, and all of it is what a serious kernel project looks like from the tooling side, which is a useful contrast with the state of the kernel itself.

## What mycelium is for, and where it sits

There are two audiences, and they are interested in very different things.

The first is the operating systems and Rust systems programming community, which follows the project for the WASI-as-syscall-interface idea and for the architecture that would let WebAssembly modules run in kernel space as well as user space. For that audience the current hello-world state is not a defect, it is the expected shape of an early-stage kernel, and the repository's own honesty is a feature.

The second is Rust developers who need bare-metal building blocks and stumble on maitake, cordyceps, mycelium-util or mycelium-alloc on crates.io. For them the kernel is irrelevant and the crates are the point.

The alternative approaches to compare against are worth naming concretely. The first is an existing WebAssembly system interface implementation used directly on top of a conventional kernel, with none of the microkernel work and none of the WASI-in-kernel-space idea. The second is a hobbyist OS written in Rust on top of a mature kernel, using the standard library rather than building one, which reaches a running system much sooner and gives up the possibility of running modules in kernel space.

mycelium takes the third position, building the kernel and the HAL and the runtime from scratch, which is the slowest route to a working system and the only one that could deliver the WASI syscall layer as a first class thing rather than as a compatibility shim. That is a research bet, not a product decision, and the repository presents it as such.

The licence is MIT, with the LICENSE file at the root, and the documentation site is mycelium.elizas.website.

## Conclusion

Adopt the mycelium crates rather than the kernel if you are looking for bare-metal Rust building blocks, since the README says these libraries may be generally useful for other projects and have been or will be published to crates.io. Do not adopt the kernel itself for anything but study, because it runs one hello world module and the project describes its own goal with the phrase someday this will do stuff. Verify first that you have a Rust nightly with the target toolchain from rust-toolchain.toml and a QEMU setup that the inoculate build tool can drive, and read CONTRIBUTING.md before setting up the environment.

## FAQ

### What is mycelium?

It is a Rust project that contains Mycelium, described in the README as an alleged operating system, intended eventually to be a microkernel-ish system running on commodity desktop hardware that executes WebAssembly modules in kernel and user space and implements WASI as its syscall layer. Right now it runs one hello world module that prints a greeting and exits.

### How do I build and run the mycelium kernel?

The README says the easiest way is to use inoculate, the project's build tool, and to launch Mycelium in QEMU with `cargo run-x64`. The environment setup details are in CONTRIBUTING.md, and the repository pins a toolchain in rust-toolchain.toml with Nix and direnv files for the development shell.

### Which Rust libraries does the mycelium repository publish?

The general purpose crates are cordyceps for intrusive data structures including lock-free MPSC queues, maitake as an async runtime construction kit for bare metal, mycelium-alloc as a buddy-block allocator, mycelium-bitfield built on const eval and declarative macros, and mycelium-util as a standard library of no_std components.

### How does the mycelium project test its crates?

The justfile runs host tests, loom concurrency model checks, miri undefined behaviour checks and doc tests. The justfile names cordyceps and mycelium-util as the crates tested under loom and miri, and it can switch the Rust toolchain away from the one pinned in rust-toolchain.toml.

## Sources

- [hawkw/mycelium on GitHub](https://github.com/hawkw/mycelium)
- [License: MIT](https://github.com/hawkw/mycelium/blob/main/LICENSE)
- [Project website](https://mycelium.elizas.website)
- [README](https://github.com/hawkw/mycelium/blob/main/README.md)
- [Releases](https://github.com/hawkw/mycelium/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hawkw-mycelium