Getting started with RidgeOS

Try RidgeOS in a VM, install it on one of the supported platforms, or build the whole distribution yourself.

Overview

RidgeOS is a modern, ARM-first Linux distribution. You install prebuilt packages with rpk — and because every package is also a port, you can rebuild any of them from source when you want to. Three platforms are supported today:

• QEMU virtual machine — the fastest way to try it, no hardware needed.
• Generic amd64 PC — the desktop reference target (x86-64, UEFI).
• OnePlus 8T — the mobile target (Snapdragon 865, aarch64).

Requirements

To try or write a prebuilt image you'll need:

• QEMU: qemu-system-x86_64 with KVM and an OVMF/UEFI firmware.
• amd64 bare metal: a 64-bit PC and an 8 GB or larger USB drive.
• OnePlus 8T: the device with an unlockable bootloader, a USB-C cable, and fastboot from the Android platform-tools.
• xz to decompress, and sha256sum to verify.

Try it & install on a generic amd64 PC

The fastest way to look around is under QEMU — nothing to flash, nothing to undo. To run on real hardware, write the same image to a disk and boot it in UEFI mode.

sha256sum -c ridgeos-amd64.img.xz.sha256
unxz ridgeos-amd64.img.xz

qemu-system-x86_64 -enable-kvm -m 4096 \
  -bios /usr/share/OVMF/OVMF_CODE.fd \
  -drive file=ridgeos-amd64.img,format=raw \
  -net user,hostfwd=tcp::2222-:22 -net nic

# replace /dev/sdX with your target disk — this erases it
sudo dd if=ridgeos-amd64.img of=/dev/sdX bs=4M status=progress conv=fsync

Flash the OnePlus 8T

The OnePlus 8T (codename kebab) boots RidgeOS via U-Boot. Flashing unlocks the bootloader and replaces Android, so back up anything you want to keep first.

adb reboot bootloader
fastboot flashing unlock

sha256sum -c ridgeos-kebab.img.xz.sha256
unxz ridgeos-kebab.img.xz

fastboot flash boot   ridgeos-kebab-boot.img
fastboot flash system ridgeos-kebab.img
fastboot reboot

First boot

On first boot RidgeOS starts the Wayland desktop — a wlroots compositor with the RidgeOS shell. On the QEMU / amd64 target an SSH server also listens on port 2222:

ssh -p 2222 root@localhost

The convergent shell adapts to the display: a desktop layout on a monitor, a phone layout on the OnePlus 8T panel.

Build from source

Every image is reproducible from the source tree. The build farm runs as a Docker Compose stack; rfarm builds the ports and rbootstrap assembles the image.

# source repo URL coming soon — see /source
git clone <ridgeos-source-url>
cd ridgeos
docker compose up -d --build

docker exec ridgeos-rfarm python3 -m rfarm.client \
  build --arch aarch64 --method cross --machines builder-amd64

rbootstrap init --target amd64
rbootstrap qemu

Managing packages

On a running system, rpk installs and removes packages from the registry:

# install a package into the running rootfs
rpk install <package>

# list what's installed
rpk list