Every Roxora image is built and checked in CI before it is released; the release notes say which ones have also been booted on a board so far. Keep a way back (another SD card, or the board's vendor image) when you try a new board or release.

Each board has up to three images per Ubuntu release. They are the same system underneath: the same kernel, the same updates, the same roxora account.

• Command line (roxora-<board>-<release>-edge-<version>.img.xz): no desktop, close to Ubuntu's server image. For a board used over SSH or the serial console, and the smallest download. It fits a 4 GB card.
• GNOME minimal (...-edge-gnome-minimal-<version>.img.xz): Ubuntu's desktop with Firefox, the App Center, Files, Settings, a terminal and a text editor (ubuntu-desktop-minimal). Pick this for a desktop; more applications can be installed later.
• GNOME (...-edge-gnome-<version>.img.xz): the full Ubuntu desktop (ubuntu-desktop), which adds LibreOffice, Thunderbird and the other applications of a default Ubuntu installation.

A desktop image is a download of 2.2 to 2.9 GB and 7 to 9 GB once written, against 0.4 to 0.5 GB and 2 to 2.7 GB for the command line image. It needs a card or drive of 16 GB or more, and a display on HDMI with a keyboard and mouse. Each board image comes with either of two kernels, edge or vendor in the file name where the examples here say edge; the FAQ says which to pick, and edge is the default. You can also start from the command line image and add the desktop later with sudo apt install ubuntu-desktop-minimal; the FAQ says what differs then.

Pick the image for your board from the website's Download page (https://roxora-os.github.io/download/) or from the releases. Download the .img.xz file and its .sha256 file. For the Radxa ROCK 4D also download the -spi.img file and its .sha256 file; the three images of one board, Ubuntu release and Roxora release come with the same bootloader, under each image's name.

Roxora Imager downloads and checks the files itself; you can skip to step 3 if you use it.

Desktop images come in parts

GitHub takes no release file of 2 GiB or more, and a desktop image is larger. It is published in parts instead: <file>.img.xz.part1, <file>.img.xz.part2 (each up to 1900 MiB), with one <file>.img.xz.sha256 for the joined file. Roxora Imager 0.1.5 and later downloads the parts, joins and checks them itself. By hand, download every part and the .sha256 file into one directory and join them in order:

cat roxora-<board>-<release>-edge-gnome-<version>.img.xz.part* > roxora-<board>-<release>-edge-gnome-<version>.img.xz

On Windows, in the Command Prompt:

copy /b <file>.img.xz.part1 + <file>.img.xz.part2 <file>.img.xz

Then check the joined file as below; the parts can be deleted once it says OK. The joined .img.xz is what step 3 writes. The Download page and SHA256SUMS in the release also give the SHA-256 of each part, to check a single part before joining.

Check the files (<release> is noble for Ubuntu 24.04 or resolute for Ubuntu 26.04; a desktop image has -gnome-minimal or -gnome after edge):

sha256sum -c roxora-<board>-<release>-edge-<version>.img.xz.sha256
sha256sum -c roxora-<board>-<release>-edge-<version>-spi.img.sha256   # ROCK 4D

Every line must end in OK.

From release 2026.11.3 on, each image also has a build provenance attestation: a signed record of the GitHub Actions run, commit and repository that built it. With the GitHub CLI:

gh attestation verify roxora-<board>-<release>-edge-<version>.img.xz --repo roxora-os/build

This works for an image joined from its parts too: the images are attested whole before they are split, and each part has an attestation of its own.

The ROCK 4D starts from SPI NOR flash, UFS or USB, never directly from an SD card. An SD card boots only through a U-Boot in the SPI NOR flash. If the flash is blank, or holds an EDK2 (UEFI) firmware, write Roxora's -spi.img to it first, with Roxora Imager over USB (Maskrom mode). Skip this step if the flash already holds a mainline U-Boot. To keep an EDK2 firmware in the flash, use the UEFI image instead (see RK3576 boards with UEFI firmware).

The ArmSoM CM5-IO needs no bootloader step: its U-Boot is on the SD card or eMMC with the image. It prefers eMMC over SD, so if the eMMC holds a bootable system, the SD card is not used.

Any of these works:

• Roxora Imager: choose the board, the image and the SD card. It checks the download, writes the card and reads it back.

• Raspberry Pi Imager: "Use custom", then the .img.xz file (for a desktop image, the file joined from its parts).

• On Linux, where /dev/sdX is the SD card (check with lsblk; everything on it is erased):

  xz -dc roxora-<board>-<release>-edge-<version>.img.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress

To install to the CM5-IO's eMMC instead, write the image there with Roxora Imager over USB (Maskrom mode).

The generic-rk3576-uefi image is for any RK3576 board that runs UEFI firmware, for example edk2-rk3576 on the Radxa ROCK 4D or the ArmSoM CM5-IO. It has no bootloader of its own and no -spi.img file: the firmware on the board starts GRUB from the image, and gives the kernel the board's device tree.

1. Install the firmware first, as its project describes: for edk2-rk3576 see its releases and flashing guide. On the ROCK 4D it goes into the SPI NOR flash; on the CM5-IO onto the eMMC or an SD card. Check that the board shows the firmware's front page on HDMI or on the serial console (1500000 baud) before you go on.
2. Download and check roxora-generic-rk3576-uefi-<release>-<branch>-<version>.img.xz as in step 1 above. <branch> is the kernel:
   • edge: Armbian's kernel, close to mainline Linux. It works with the firmware's own device tree and with Armbian's (below).
   • vendor: Rockchip's BSP kernel (Linux 6.1), with the drivers of Rockchip's own SDK. It needs Armbian's device tree for that kernel, so turn on the firmware's DTB override first, as described in Using Armbian's device tree; the firmware's own device tree is written for mainline Linux. Its serial console is ttyFIQ0.
3. Write the image to a USB drive, an NVMe drive or an SD card, the same way as in step 3 above (Roxora Imager, Raspberry Pi Imager, or xz -dc ... | sudo dd ...). An NVMe drive can be written in another computer with a USB adapter. Do not write it over the medium that holds the firmware: on the CM5-IO with the firmware on its SD card, put the image on NVMe or USB; with the firmware on the eMMC, the SD card is free.
4. Connect the drive and power the board on. The firmware starts \EFI\BOOT\BOOTAA64.EFI from the drives in its boot order; if it starts another system, choose the drive in its boot manager. GRUB shows its menu for three seconds, then starts the newest kernel. The first boot then goes on as in step 4 below; the host name is generic-rk3576-uefi.

Using Armbian's device tree instead of the firmware's

By default the kernel gets the firmware's device tree. The vendor image needs this override; for the edge image it is optional. The image also has Armbian's device trees for RK3576, from the installed kernel, on its EFI system partition (/boot/efi/dtb/rockchip/); every kernel update refreshes them. To boot with those instead, on edk2-rk3576:

1. At power on, enter the firmware setup (Escape on edk2).
2. Go to Device Manager, RK3576 Platform Configuration, ACPI / Device Tree.
3. Set "Support DTB override & overlays" to Enabled. Leave "Firmware Fix-ups" enabled and both paths empty.
4. Save, and reset the board.

The firmware then loads \dtb\rockchip\<board>.dtb (for example rk3576-rock-4d.dtb or rk3576-armsom-cm5-io.dtb) from the drive it boots from. A debug build of the firmware prints FdtPlatform: Loaded FDT override on the serial console when it does. To go back, set the option to Disabled again. If the board does not boot with the override, the firmware setup is still reachable at power on.

Kernel updates through apt rewrite the GRUB menu for the new kernel. Armbian's kernel package replaces the kernel it updates (one package per kernel branch, not one per version), so the menu lists one kernel per installed branch. GRUB itself is updated from the Ubuntu archive.

Insert the card, connect Ethernet and power the board on. The first boot takes a minute longer than later ones: the root file system grows to fill the card, and cloud-init creates the SSH host keys.

Log in on the console or over SSH:

• user roxora, password roxora;
• the password must be changed at the first login;
• the host name is the board name, for example radxa-rock-4d, and the wired interface gets its address by DHCP.

The root account is locked; use sudo. Change the password before you connect the board to a network you do not trust.

Wi-Fi on a command line image

Images after 2026.11.4 have NetworkManager's text interface for Wi-Fi. On the console or over SSH:

sudo nmtui

Choose "Activate a connection", the network, and enter its password. Or in one line:

sudo nmcli device wifi connect "<network name>" password "<password>"

The connection is kept and comes up again at every boot. nmcli device shows the state. NetworkManager runs only Wi-Fi (and mobile broadband) on these images: wired Ethernet stays with systemd-networkd, as before, and nmcli device lists it as unmanaged. If your network does not show in the list, set the Wi-Fi country, which decides the channels the board may use: sudo hwtool wifi country <code>.

The image includes hwtool for the board's hardware settings: hwtool info shows what it found, and hwtool --help lists what it can change.

First boot of a desktop image

A desktop image starts the login screen (GDM) on HDMI. Choose the user roxora and enter the password roxora. The login screen then says the password must be changed: enter roxora once more as the current password, then a new password twice; Ubuntu's password rules apply. After that the desktop starts.

The first boot takes a few minutes longer than later ones. Besides growing the root file system, snapd installs the snaps that are in the image (Firefox, the App Center and the snaps they need); until it has finished, their icons are missing from the application list or do not start. No network is needed for that.

SSH works as on the command line image, with the same account; changing the password over SSH or on the console first also counts for the login screen. The network is run by NetworkManager, as on any Ubuntu desktop: wired Ethernet gets its address by DHCP, and Wi-Fi is set up from the system menu (nmtui and nmcli work there too).

Hardware Tool (the GTK app of hwtool) is in the application list, and the hwtool command works as on the command line image. The wallpaper is Roxora's Facet; the other Roxora wallpapers and Ubuntu's are in Settings, Appearance.

Ubuntu packages come from the Ubuntu archive, the kernel, device tree, U-Boot and firmware packages from Armbian's repository, and Roxora's own packages from Roxora's repository:

sudo apt update && sudo apt full-upgrade

Security updates of Ubuntu packages install automatically (unattended-upgrades), as on Ubuntu server; the others arrive with the command above. On a desktop image the snaps update on their own from the snap store, as on Ubuntu.

Updating to a new Roxora release

From 2026.11.5 on, an image has Roxora's apt repository set up and a release package for its flavor: roxora-cli, roxora-desktop-gnome-minimal or roxora-desktop-gnome, with roxora-release, which they share. When a new Roxora release comes out, its release packages reach the repository within the hour, and the command above brings them: the system then has what that release changed in its image, as far as packages can carry it. That is new packages for the flavor (2026.11.5 adds NetworkManager to the command line image), new versions of hwtool and the wallpapers, Roxora's apt sources and pins and cloud-init's settings, and the steps a release needs that apt cannot express, which the packages run once. cat /etc/roxora-release shows the release and the flavor.

What an update does not do: it does not repeat the first boot (the account, the SSH host keys, the size of the root file system stay as they are), it does not write a new bootloader to the SPI flash or the card (step 2 and the hardware test say how to do that), and it does not reboot; a new kernel takes effect at the next reboot, as with any kernel update. Configuration files you changed stay yours: when a release package has a new version of one, apt asks before it replaces it, as Ubuntu does for its own packages.

Images up to 2026.11.4 do not have the repository. Add it once, with its key, on the console or over SSH:

sudo curl -fsSL -o /usr/share/keyrings/roxora-archive-keyring.gpg https://roxora-os.github.io/apt/roxora-archive-keyring.gpg
gpg --show-keys /usr/share/keyrings/roxora-archive-keyring.gpg
. /etc/os-release && printf 'Types: deb\nURIs: https://roxora-os.github.io/apt\nSuites: %s\nComponents: main\nSigned-By: /usr/share/keyrings/roxora-archive-keyring.gpg\n' "${VERSION_CODENAME}" | sudo tee /etc/apt/sources.list.d/roxora.sources
sudo apt update

The second command shows the key: its fingerprint must be 07353CCFAF21725418E3CE4798FC2BE6A9A8952D. If it is not, delete the file and stop. Then install the release package of your image's flavor:

apt list --installed 'ubuntu-desktop*' tells a desktop image apart: it lists ubuntu-desktop-minimal on GNOME minimal and ubuntu-desktop on GNOME; a command line image has neither. --no-install-recommends gives the packages the new image has and no more (without it, apt would add ModemManager and PPP to NetworkManager on a command line image). The release package takes over Roxora's configuration files the image already has: the apt sources and pins and cloud-init's settings. Unchanged ones it replaces with its own; for one you changed, apt asks first. Finish with

sudo apt update && sudo apt full-upgrade

From then on that command brings each new release.

From Ubuntu 24.04 to 26.04

Upgrading the Ubuntu release of an installed system is not supported yet: the procedure below passes in CI, on images in a chroot, but nobody has booted a board after it. Until then, writing the 26.04 image is the safe way. If you try it, have a backup of your data.

sudo apt update && sudo apt full-upgrade
sudo do-release-upgrade

The system needs Roxora's repository and its release package first (any image from 2026.11.5 on, or one added to as above). The upgrader then moves Roxora's and Armbian's sources to 26.04 with Ubuntu's own (roxora-release names them in /etc/update-manager/release-upgrades.d/roxora.cfg), and installs the 26.04 release packages, which put the rest in order. Other third-party sources (PPAs, for example) are turned off, as on Ubuntu. Accept what the upgrader proposes, and reboot when it asks. Afterwards cat /etc/roxora-release says ROXORA_UBUNTU_CODENAME=resolute. What differs from a new 26.04 image is in Architecture.

Report problems at https://github.com/roxora-os/build/issues. See the FAQ for where kernel and hardware problems belong.