Installing next to Windows on one disk? See Dual-boot with
Windows — you make the free space first. Already running Arch?
Convert your machine in place instead of reinstalling.
1. Get an ISO
Public ISO availability is tracked on ryoku.dev. You can also build the image yourself from the monorepo; see ISO build recipe for the full procedure and the hardware notes. A USB stick of at least 8 GB is fine. Flash the ISO withdd, balenaEtcher,
or Ventoy.
2. Verify the signature
Every release is signed byRyoku Releases <[email protected]>. Always check
the imported key’s fingerprint matches before trusting it. The canonical
public key lives in the repo at
keys/ryoku-release-key.pub.asc,
bound to git history.
3. Try in a VM first (optional)
Ryoku targets modern desktops and laptops. If you want to walk through the installer before committing to bare metal, boot the ISO in QEMU/KVM, VirtualBox, or VMware with at least 16 GB RAM and a 60 GB virtual disk. For first-class daily use on real hardware, target 32 GB RAM and 80 GB free disk.4. Boot the installer
The ISO is a stock Arch live image with one job: boot the machine and drop you straight into the Ryoku installer.1
Auto-login to the installer session
The kernel and archiso initramfs come up,
agetty logs in as root on
tty1, and the login shell starts a tiny Wayland kiosk (cage) running
a terminal (foot) that runs ryoku-tui. The serial console and the
other VTs stay plain root shells for headless or recovery use.2
Answer the prompts
ryoku-tui walks you through keyboard, locale, time zone, network,
hardware profile, disk strategy, user, and (optional) LUKS encryption.
Nothing is written to disk until you confirm on the review screen.3
Hand off to the backend
On confirm, the TUI exports your choices as
RYOKU_* environment
variables and runs ryoku-install. The same variables can be set by hand
on the serial console for a headless install; RYOKU_DRYRUN=1 runs every
stage without touching the disk.5. What the backend does
ryoku-install runs the stages below, each in its own file under
installation/backend/lib/. It streams its log to stdout and emits
@@RYOKU_STEP <id> sentinels so the TUI can draw staged progress; on success
it prints @@RYOKU_DONE and exits 0.
The
ryoku-gpu and ryoku-monitor helpers seed ~/.config/hypr/gpu.lua and
~/.config/hypr/monitors.lua on first login from the Hyprland autostart, so
the installer does not run them.
6. Reboot
When the backend finishes, reboot and remove the USB. SDDM appears; pick the Ryoku session and log in. Continue with First boot for what to expect on the desktop and the first few keys worth pressing.Hardware notes
The shipped GPU profiles areamd-nvidia (hybrid laptop with NVIDIA + AMD),
amd, intel, and vm. Secure Boot is not configured automatically; the
ISO build recipe tracks the working hardware list
and the harmless chroot warnings you can ignore.