OnyxOS is an operating system for RISC-V, written from scratch. It started as a system for the OC2R Minecraft mod (OpenComputers 2, which emulates RISC-V with Sedna), and it also boots in QEMU. A Milk-V Duo S port is a goal, not yet verified.
Everything in the stack is our own: a monolithic kernel in Rust, a bootloader in C++, a Rust shell, and a self-hosting C compiler that builds the userland.
$ bash scripts/bootstrap.sh && bash scripts/build-all.sh && bash scripts/run-qemu.shLog in as root and you get a shell, a TCP/IP stack, FAT32 and OnyxFS v2,
plus Lua, vim and a few more apps built with our own compiler.
| Area | State |
|---|---|
Boot in QEMU virt (OpenSBI, OnyxBoot, kernel, init, login) |
Works |
| Boot inside OC2R (Sedna) | Works, verified in-game |
| TCP/IP, UDP, DHCP, DNS | Works; HTTP only, no TLS |
| FAT32, OnyxFS v2 (journal, snapshots) | Works |
| Self-hosting compiler | Works (make selfhost-test) |
| SMP | Experimental, multi-hart boots are not stable yet |
| Unprivileged user sessions | Unfinished: login does not install uid/gid yet |
| Real single-board hardware (Milk-V Duo S) | Not verified |
| GUI (window manager, compositor), Java runtime | Planned |
This repository is the meta-project: it vendors the other Onyx repositories as sibling checkouts, builds all of them, and assembles the boot disk image and QEMU launch scripts.
| Component | Language | Description |
|---|---|---|
| OnyxBoot | C++20 | Bootloader: FDT, VirtIO, SDHCI, FAT32/ext4, GPT, boot menu |
| OnyxKernel | Rust | Monolithic kernel: SMP, Sv39 MM, VFS, TCP/IP, OnyxFS v2, FAT32, wide syscall ABI |
| OnyxShell | Rust | /bin/osh: built-in commands, tab completion, history, pipes/redirects, globbing, job control |
| OnyxCompiller | C99 | Self-hosting C compiler: C99 -> RV64 -> .onx, libonyxc |
| OnyxApps | C99 | Optional userland applications, built with OnyxCompiller |
| OnyxOS (this repo) | - | Build orchestration, docs, disk image assembly |
$ # 1. Install build dependencies
$ sudo pacman -S cmake base-devel curl libarchive # Arch
$ sudo apt install cmake build-essential libcurl4-openssl-dev libarchive-dev # Debian/Ubuntu
$ # 2. Clone every Onyx repository as a sibling checkout
$ bash scripts/bootstrap.sh
$ # 3. Build every component and assemble the boot disk image
$ bash scripts/build-all.sh
$ # 4. Boot it in QEMU
$ bash scripts/run-qemu.shscripts/bootstrap.sh reads repository URLs from Onyx.vent and checks out
exact commits from Onyx.lock.json into .vent/repos/. It uses Python 3 and
Git directly; Vent is not required. Existing dirty or symlinked repositories
are never checked out automatically. scripts/build-all.sh verifies the lock
before building and writes artifacts to .build/.
For local sibling checkouts or symlinks, explicitly opt into development inputs:
$ ONYX_DEPS_MODE=workspace bash scripts/build-all.sh
$ ONYX_DEPS_MODE=workspace bash scripts/build-oc2r.shThis mode reports revisions and dirty status; it does not claim a locked build. See dependency locking for release updates.
OnyxOS/
├── Onyx.vent # Component source URLs
├── Onyx.lock.json # Exact component Git revisions
├── .vent/
│ └── repos/ # Sibling checkouts (after bootstrap.sh)
├── scripts/
│ ├── bootstrap.sh # Clone exact locked component revisions
│ ├── build-all.sh # Build every component + assemble the disk image
│ ├── run-qemu.sh # Boot in QEMU (dev mode or full boot chain)
│ ├── mk-onyxfs-disk.sh # Build the FAT32 + OnyxFS partitioned disk image
│ ├── qemu-smoke.sh # Headless boot smoke test
│ └── qemu-interactive-smoke.sh # Interactive boot smoke test
├── docs/
│ ├── architecture/ # Boot chain, memory layout, privilege rings
│ ├── dev/ # Building, contributing, roadmap
│ ├── hardware/ # UART, PLIC, CLINT, VirtIO
│ ├── internals/ # Coding style, error handling conventions
│ ├── kernel/ # Process model, memory management, interrupts
│ ├── shell/ # Shell commands and internals
│ └── lore/ # Project history and notes
├── Makefile
└── README.md
scripts/run-qemu.sh supports two modes:
$ bash scripts/run-qemu.sh boot # default: full chain via OnyxBoot + a disk image
$ bash scripts/run-qemu.sh dev # fast dev loop: QEMU loads the kernel ELF directly, no disk imageUseful environment variables:
| Variable | Effect |
|---|---|
QEMU_MEM |
RAM size (default 256M) |
QEMU_EXTRA |
Extra QEMU flags, e.g. -s -S for GDB |
SMP is controlled by passing -smp N via QEMU_EXTRA, or by invoking QEMU
directly (see the OnyxKernel README
for the full manual command line and its multi-hart caveat - the kernel
supports up to 8 harts, but multi-hart boots are still experimental).
$ cd .vent/repos/OnyxKernel
$ cargo kbuild # alias for: cargo build --release -p onyx_kernel --target riscv64gc-unknown-none-elf$ cd .vent/repos/OnyxBoot
$ make -j$(nproc)$ cd .vent/repos/OnyxShell
$ bash build.sh$ cd .vent/repos/OnyxCompiller
$ make # native Linux binary
$ make onyxcc-onx # cross-compiled .onx for OnyxOSOC2R is a Minecraft (NeoForge) mod that adds virtual computers with 64-bit RISC-V emulation. OnyxOS can boot directly inside the game.
OC2R downloads a computer's firmware from a GitHub repository using an
oc2r-firmware.json manifest at the repository root. The mod reads it,
follows the image link, and flashes that image into the virtual machine.
{
"name": "OnyxOS",
"version": "0.3.0",
"layout": "minux",
"image": "https://github.com/DivByDiamond/OnyxOS/releases/latest/download/onyx-flash.img"
}| Field | Value | Description |
|---|---|---|
name |
OnyxOS |
Firmware name |
version |
e.g. 0.3.0 |
Matches the OnyxKernel workspace Cargo.toml version |
layout |
minux |
Flash layout scheme (below) |
image |
direct link to onyx-flash.img |
The flat flash image attached to a GitHub Release |
minux layout (flash is exactly 15 MB):
| Offset | Size | Contents |
|---|---|---|
0x000000 |
- | fw_jump.bin (OpenSBI, from the OC2R mod's src/main/scripts/firmware_files/) |
0x200000 (2 MB) |
- | OnyxKernel image (ELF, built by cargo) |
| up to 15 MB | - | zero-filled |
$ # 1. Resolve locked dependencies into .vent/repos/
$ make deps
$ # 2. Build the bootloader and kernel
$ make -C .vent/repos/OnyxBoot
$ cargo build --release -p onyx_kernel --target riscv64gc-unknown-none-elf \
--manifest-path .vent/repos/OnyxKernel/Cargo.toml
$ # 3. Place a real OpenSBI build at firmware/fw_jump.bin
$ # (from the OC2R mod: src/main/scripts/firmware_files/fw_jump.bin)
$ # 4. Assemble a 15 MB image using the minux layout
$ dd if=/dev/zero of=onyx-flash.img bs=1M count=15
$ dd if=firmware/fw_jump.bin of=onyx-flash.img conv=notrunc
$ dd if=.vent/repos/OnyxKernel/target/riscv64gc-unknown-none-elf/release/onyx-kernel \
of=onyx-flash.img bs=1M seek=2 conv=notrunc.github/workflows/release.yml runs on every pushed git tag (e.g. v0.3.0):
- Builds every component (
make depsresolves exact component commits fromOnyx.lock.json). - Assembles
onyx-flash.img(15 MB,minuxlayout). - Creates a GitHub Release and attaches the image.
The manifest's image field points at
/releases/latest/download/onyx-flash.img, which GitHub resolves to the
newest release's asset automatically.
To produce a working release you need to either:
- Commit a real
fw_jump.bin(OpenSBI) atfirmware/fw_jump.bin, or set the repository variableOC2R_FW_JUMP_URL(without either, CI builds an image with a placeholder that will not boot); and - Push a tag such as
v0.3.0- CI builds and uploads the image.
Every push to main also publishes a preview image as a workflow artifact,
without creating a Release.
Optional userspace programs live in the
OnyxApps monorepo (a text
editor, a system monitor, an HTTP client, and more). Each application has
its own README.md under apps/<name>/. Build with make in the OnyxApps
repository root; CI also publishes build/*.onx artifacts.
All applications run on top of the kernel's ANSI/VT100 framebuffer
terminal (fb_term/ansi.rs): SGR colors, cursor positioning, erase
sequences, scroll regions, per-process termios via TCGETS/TCSETS, and
TIOCGWINSZ reporting the real framebuffer grid.
Planned work and open issues are tracked in
docs/dev/roadmap.md (project-wide milestones) and
OnyxKernel's todo.md
(kernel-level tracking, including in-progress investigations).
GPL-3.0-or-later. See LICENSE.
