# Redox OS Build System: Building and Booting the Rust Microkernel Operating System

> Redox is a full operating system written in Rust around a microkernel, and this repository is its build system, not the kernel itself. Here is what the cookbook does, how to build an image with Podman, and where the rough edges are.

**redox-os/redox** — Mirror of https://gitlab.redox-os.org/redox-os/redox

- Repository: https://github.com/redox-os/redox
- Stars: 16,598 · Forks: 1,027
- Language: Rust
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/redox-os-redox

## What Redox OS Is, and Why This Repository Is Not the Kernel

Redox is an open-source operating system written in Rust, built on a microkernel architecture. The README states that it is inspired by seL4, MINIX, Plan 9, Linux and BSD, and that it aims to be reliable, secure, usable, correct and free. The same README is explicit that Redox is not just a kernel: it ships a filesystem, a display server and core utilities as separate components.

The repository you are reading about is the Build System, and the README says so in its first sentence. The kernel is a different repository, as are RedoxFS (the default filesystem), relibc (the C POSIX library written in Rust), Ion (the default shell), Orbital (the display server and window manager), pkgutils (the current package manager) and Redoxer, a tool for developing for Redox from Linux. If you clone this one expecting kernel source, you will find Makefiles, recipes, scripts, a Podman directory and a Cargo workspace instead.

That split matters for who this is for. The build system is aimed at people who want to produce a bootable Redox image, either for a virtual machine or for real hardware, and at developers adding or updating packages. The Cargo.toml names the workspace package redox_cookbook and defines several binaries: repo, repo_builder, repo_editor and cookbook_redoxer, with a library named cookbook. The tui feature is on by default and pulls in ratatui, ansi-to-tui and strip-ansi-escapes, so the default experience is a terminal interface. A comment in the manifest notes that building without the tui feature is still a TODO, which tells you the non-interactive path is not the tested one.

## How the Cookbook, Recipes and Makefile Fit Together

The top level of the repository shows the shape of the pipeline: a Makefile, a mk/ directory of included makefiles, a recipes/ directory, config/, scripts/, bin/, podman/, and a flake.nix with a flake.lock for Nix users. The Makefile starts by including mk/config.mk and mk/depends.mk, which means build paths, tool paths and dependency checks are configuration rather than hardcoded commands.

The default target is $(BUILD)/harddrive.img. There is a live target that removes $(BUILD)/redox-live.iso and rebuilds it, an image target that removes both the hard drive image and the live ISO before rebuilding, and a rebuild target that additionally removes $(BUILD)/repo.tag. The presence of repo.tag suggests the repo binary caches something between runs, and that a stale tag is a plausible cause of confusing builds. The clean target unmounts $(BUILD)/filesystem/ and /tmp/redox_installer/ before deleting build output, which implies the build mounts filesystems during image creation and can leave them mounted if it fails.

The cookbook itself is the Rust program that consumes recipes and produces a repository of packages. Its dependencies in Cargo.toml include pkgar, pkgar-core and pkgar-keys from the pkgutils GitLab group for package archives and signing, redox-pkg, redox_installer and redoxer. That dependency list is the clearest statement of what the tool does: it builds packages, indexes them, and hands them to the installer that assembles the image. The Makefile also carries a NOT_ON_PODMAN variable with a comment saying it exists to mark that it is not safe to execute the cookbook binary, and the clean and distclean targets branch on PODMAN_BUILD. The build system is designed to run the cookbook inside a container, and running it outside is treated as the exception.

## Building a Redox Image with Podman

The README points to the Redox Book for build instructions, specifically the Podman build page, and the repository ships podman/ and podman_bootstrap.sh to support that route. The Book is the authority here; the commands below are the ones the repository's own layout and documentation point at, and you should read the Book page before running them.

First clone the build system and enter it. The README notes this GitHub repository is a mirror of the GitLab project, so the GitLab URL is the canonical remote.

```bash
git clone https://gitlab.redox-os.org/redox-os/redox.git
cd redox
```

The repository provides a bootstrap script for the container tooling. Run it once, then build the default target, which the Makefile defines as $(BUILD)/harddrive.img.

```bash
./podman_bootstrap.sh
make all
```

If you want a live ISO instead of a hard drive image, the Makefile has a live target that removes any previous $(BUILD)/redox-live.iso and rebuilds it. The popsicle target depends on that ISO and launches popsicle-gtk to write it to a USB device.

```bash
make live
make popsicle
```

When the build finishes you should have a bootable image under the build directory, and the Redox Book's running-in-a-virtual-machine page covers booting it. If a build fails after mounting filesystems, the clean target is the documented way out: it unmounts $(BUILD)/filesystem/ and /tmp/redox_installer/ before removing output. For a deeper reset, distclean also runs fetch_clean. If you suspect the cached repository state, rebuild removes $(BUILD)/repo.tag along with the images.

## Where the Build System Gets in Your Way

The first limitation is stated by the project itself: the Cargo.toml comment says making the build work without the tui feature is a TODO. The default feature set is the supported one, and the interactive terminal interface is not optional in practice.

The second is the container assumption. The Makefile's NOT_ON_PODMAN variable exists to flag that executing the cookbook binary directly is not safe, and the clean and distclean targets only run the direct path when PODMAN_BUILD is not 1. If your environment cannot run Podman, or you are trying to build inside a restricted CI runner, you are outside the path the build system is written for. The Makefile even prints a message saying it will not run cookbook clean when the container is not built.

The third is the mount and cleanup behaviour. Both clean and image unmount $(BUILD)/filesystem/ and /tmp/redox_installer/ with the leading minus that tells make to ignore failures. That is a reasonable defensive choice, but it also means a failed build can leave a mount behind without the build stopping, and the next run may behave oddly until you unmount by hand.

Finally, the hardware question. The README links a hardware compatibility page in the Book and the repository carries HARDWARE.md. Redox is not a general purpose Linux replacement, and the topics list on the repository includes BSD, FreeBSD, GNU, GNU Hurd, Linux, MINIX, OpenBSD, Plan 9 and seL4, which describes a lineage and a set of comparisons rather than a compatibility promise. If your target machine is not listed, the build may succeed and the boot may not.

## The Alternative: Redoxer for Development, and Linux for Everything Else

The most useful comparison is inside the Redox project itself. Redoxer is described in the README as a tool for easy Redox development on Linux, and the build system depends on the redoxer crate. The difference in approach is direct: the build system produces a whole operating system image with a kernel, filesystem, display server and userland, while Redoxer runs Redox-targeted programs from a Linux host. If your goal is to compile and test a Rust program against relibc, Redoxer is the shorter path. If your goal is to see Redox boot, you need the build system.

The external alternative is the operating system you already run. On Linux, a container gives you a POSIX userland, a package manager and hardware support that Redox does not claim to match. Redox's answer is architectural rather than practical: a microkernel with drivers and services in separate processes, a Rust C library, and a Rust shell. That is a different set of trade-offs, not a drop-in replacement. The README's own framing, that Redox provides source code compatibility with many Rust, Linux and BSD programs, is a statement about compiling source, not about running existing binaries.

## Maintenance, Licensing and Upgrade Cost

The repository is not archived, and the last push was on 2026-09-20. The most recent release is 0.9.0 from 2025-09-22, preceded by 0.5.0 in 2019 and 0.3.5 in 2018. That release history is worth reading literally: the project went roughly six years between the 0.5.0 and 0.9.0 tags, so pinning to a release means pinning to something that may be far behind master. Building from master means tracking a moving target, and the Makefile's rebuild target, which deletes $(BUILD)/repo.tag, exists precisely because cached repository state can go stale between builds.

Upgrade cost is dominated by the toolchain. rust-toolchain.toml pins the Rust version, Cargo.lock pins the crate graph, and flake.lock pins the Nix inputs, so a checkout is reproducible in principle but requires the matching toolchain. Several dependencies are git dependencies on the Redox GitLab, including pkgar, pkgar-core, pkgar-keys, redox-pkg, redox_installer and redoxer. Those are not crates.io versions, so a change on GitLab can affect your build without any version number moving.

The license is MIT, per the repository metadata and the LICENSE file, and the README carries an MIT badge. MIT is permissive, so redistribution and modification are allowed subject to its terms. Note that the repository also contains TRADEMARK.md, which is separate from the code license and typically governs use of the project name and logo. That is a distinction worth checking if you plan to redistribute images, and it is not something this article can resolve for you.

## Conclusion

Adopt this if you are comfortable in Rust and want to work on an operating system whose kernel, C library, filesystem and shell are all in one language, and if you accept that the build system lives on GitLab while GitHub only mirrors it. Do not adopt it if you need a stable POSIX environment for production services today, or if your hardware is not on the supported list. Before building, read the Podman build instructions and HARDWARE.md, confirm your CPU and GPU appear there, and check whether the 0.9.0 release or the current master branch is the base you actually want.

## FAQ

### How do I install Redox OS?

The README does not give an installation procedure directly; it points to the Redox Book, including the Podman build page and the pages on running Redox in a virtual machine or on real hardware. The repository itself is the build system, so you build an image rather than install a package.

### What is Redox OS written in?

Redox is written in Rust. The README describes it as an open-source operating system written in Rust, a language with a focus on safety, efficiency and high performance, and the build system's Cargo.toml shows the same language throughout.

### Does Redox OS use a microkernel?

Yes. The README states that Redox uses a microkernel architecture and that it is inspired by seL4, MINIX, Plan 9, Linux and BSD. The kernel lives in a separate repository from this build system.

### What is the repository redox-os/redox actually for?

It is the build system for Redox OS, as the README states in its opening line. It contains the Makefile, recipes, scripts, Podman configuration and the Cargo workspace named redox_cookbook that together produce a bootable image.

### Why does the Redox build system require Podman?

The Makefile defines a NOT_ON_PODMAN variable with a comment saying it marks that executing the cookbook binary is not safe, and the clean and distclean targets branch on PODMAN_BUILD. The build is designed to run the cookbook inside a container.

## Sources

- [Issues](https://github.com/redox-os/redox/issues)
- [License: MIT](https://github.com/redox-os/redox/blob/master/LICENSE)
- [README](https://github.com/redox-os/redox/blob/master/README.md)
- [redox-os/redox on GitHub](https://github.com/redox-os/redox)
- [Releases](https://github.com/redox-os/redox/releases)

---

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