v0.1.0-beta.13 195Docs

· SYSTEM DOSSIER

Ryoku

@ ryoku.dev · public beta

LOCAL --:--:--

Compositor
Hyprland
Shell
Quickshell
Base
Arch Linux
Theming
wallust · matugen
Delivery
signed packages
30Hub pages
479Settings
10Bar skins
1Source
INK RAMP · 4.6:1 → 12:1
Install RyokuSource

195 stars 9 forks GPL-3.0 open source

RYOKU-BETA-18
EditionNo. 0018v0.1.0-beta.13
SCROLL

A hand-built Arch Linux desktop, its installer, and the system that rebuilds it exactly. One repository. The live machine is only a target.

The bar, launcher, lock screen, and capture tool are one shell, not a pile of widgets. You edit the repo and redeploy.

ARCH LINUX
00 // RYOKU-BASE

one source of truth. the repo is the machine; a live box is only a target.

POWERBEAUTY
A marble fist gripping a katana, engraved irezumi across the stone, dithered to bone
01 // POWER

Power.

Control you can reach. Runs on day one, reproducible from one repo.

A blindfolded marble Lady Justice with scales and sword, engraved irezumi, dithered to bone
02 // BEAUTY

Beauty.

Coherent on purpose. One look, one motion, theming that follows the wallpaper.

Extras and plugins

Ryoku ships opinionated, then stays out of the way. Add capability from the Hub, or drop in a widget you wrote. Both stay native to the desktop.

01 // EXTRAS

Extras

One-click bundles from the ryoku-extras catalogue. The Hub installs and removes them.

  • 01Curated bundles from the ryoku-extras catalogue. Install or remove in one click.
  • 02Swap the CachyOS kernel, add repos and workflows. Routed through pacman and AUR.
  • 03Every action runs in a floating terminal and reports back. Nothing happens unseen.
02 // PLUGINS

Plugins

You write the logic and one view. The shell owns look, motion, sizing, and placement, so it stays native.

~/.local/share/ryoku/plugins/<id>/

  • manifest.jsonwhat it is + defaults
  • service/Main.qmllogic and state
  • content/Widget.qmlone view
  • bin/scripts it runs

· Preinstalled

Everything, already installed.

A fresh Ryoku box isn't a bare Arch install you spend a weekend furnishing. It boots into a finished desktop with the apps, tools, and toolchains in place. Here's the honest inventory.

~90Arch packages
20+first-party Ryoku packages
13–15 GiBon disk, fresh

力 // PREINSTALLED MANIFEST

What ships out of the box

Every application, CLI, TUI, daemon, and dependency on a default install. Pulled from the Arch repos, the signed [ryoku] repo, and a small AUR set built after install.

The Ryoku desktop

Ryoku’s own packages, built from the monorepo and served from the signed [ryoku] repo.

  • ryoku-shellBar, pill, launcher, overview, capture, lock screen
  • ryoku-hubRyoku Settings, the control center
  • ryokuThe CLI: update, doctor, rollback, snapshots
  • ryoku-rashinThe live system-map vault
  • ryoku-blobsThe shared Ryoku.Blobs QML plugin
  • gpkGlazePKG, the RyokuArch package manager
  • awwwThe animated wallpaper daemon
  • ryomotionScreen-demo recorder and editor
  • ryostoreCatalogue of rices, bundles, bar styles
  • ryowallsWallpaper browser, preview, and AI enhance
  • ryovmThe virtual-machine manager
  • Hyprland pluginshyprglass, imgborders, dynamic cursors, and more, toggled from the Hub
  • ryoku-cursorsThe default Bibata pointer set (+ Material variant)

Core system & boot

Kernel, initramfs, the encrypted-Btrfs boot chain, and automatic snapshots.

  • base, base-develCore system and build tools
  • linux, linux-firmwareThe stock kernel and firmware
  • rustShipped so every box can build its Rust dependencies
  • dkms, mkinitcpioOut-of-tree modules; the initramfs
  • btrfs-progs, cryptsetupBtrfs tooling and LUKS encryption
  • limine, plymouthThe bootloader and the boot splash
  • snapper, snap-pacSnapshots around every pacman transaction

Networking, Bluetooth & audio

Connectivity and a full PipeWire stack with the Bluetooth codecs.

  • networkmanager, iwdNetworking and the default Wi-Fi backend
  • wpa_supplicant, iwThe WPA3 fallback backend and power-save control
  • bluez, bluez-utilsThe Bluetooth stack and bluetoothctl
  • pipewire (+ pulse, alsa, audio)The audio server and A2DP codecs
  • wireplumberThe PipeWire session manager
  • rtkit, alsa-utilsRealtime audio scheduling; the classic mixers

Graphics & the session

The Wayland compositor, the Qt6 runtime, portals, and the themes.

  • hyprland, xorg-xwaylandThe compositor and X11 app support
  • mesa, vulkan-icd-loaderThe GL and Vulkan base
  • qt6-*wayland, declarative, 5compat, svg, multimedia — the shell runtime
  • xdg-desktop-portal-*Screen-share (Hyprland) and file chooser (GTK)
  • hyprpolkitagentThe polkit authentication agent
  • gst-plugins-*GStreamer media codecs
  • sddmThe login greeter
  • polkit, gnome-keyringAuthorization and the secrets store
  • papirus + adwaita iconsThe icon and dark GTK themes
  • flatpakThe portable app channel

Wayland tools

The small daemons the desktop leans on every session.

  • matugenRecolors everything from the wallpaper
  • hypridle, hyprsunsetIdle/lock management and the night light
  • brightnessctl, ddcutilLaptop and external-monitor brightness
  • upower, power-profiles-daemonBattery status and power profiles
  • grim, slurp, hyprpickerScreenshot, region select, color picker
  • wl-clipboard, cliphistThe clipboard and its history
  • playerctlMedia control over MPRIS
  • fuzzelA fallback launcher

Everyday apps

The applications you actually open on day one.

  • chromiumThe web browser
  • kittyThe default terminal
  • mpv (+ mpris)The media player
  • nautilus (+ python)The file manager and its Ryoku stash actions
  • spotify-launcherSpotify, wired to the desktop Canvas widget

Terminal, CLI & TUI

A command line that’s already comfortable.

  • fish, starshipThe default shell and prompt
  • bat, eza, fd, fzf, ripgrep, zoxideThe modern coreutils layer
  • fastfetch, jqSystem readout and JSON on the CLI
  • git, github-cli, lazygitVersion control and a git TUI
  • neovimThe editor
  • btopThe resource monitor
  • yaziA terminal file manager

Capture & shell helpers

Everything behind the pill’s screen tools, plus what the shell shells out to.

  • quickshellThe framework the whole shell UI runs on
  • cavaThe audio visualizer
  • waifu2x-ncnn-vulkanGPU AI upscaler for HD export and Enhance
  • imagemagick, ffmpeg, yt-dlpImage/media processing and download
  • tesseract, zbarOCR text grab and QR scanning
  • gpu-screen-recorder, wf-recorderScreen recording, with a fallback
  • wtype, libqalculate, songrecVoice typing, the calculator, Recognize Music
  • openrgbKeyboard and LED accent sync

Developer toolchains

Every machine is dev-ready the moment it boots.

  • goThe Go toolchain
  • nodejs, npmNode and npm
  • python, python-pip, python-pipxPython with pip and pipx
  • miseA runtime version manager

Gaming & virtualization

A Bazzite-style gaming stack and the base VM tooling.

  • gamescopeA nested micro-compositor that isolates a game
  • gamemodeThe performance governor Steam invokes
  • mangohudThe FPS and frametime overlay
  • qemu-desktop, edk2-ovmf, virglrendererThe base VM stack (passthrough pieces install on demand)

Fonts

UI text, Japanese labels, emoji, terminal glyphs, and the icon symbols.

  • inter-font, otf-space-groteskThe UI sans stack
  • noto-fonts (+ cjk, emoji)Latin, Japanese, and emoji coverage
  • ttf-*-nerd (jetbrains, firacode, hack)Terminal and code fonts with glyphs
  • ttf-material-symbols-variableThe icons the bar and pill are drawn from

From the AUR (after install)

Built in the post-install step. Best-effort, online; the box comes up fine without them and they arrive on the next pass.

  • yay-binThe AUR helper, bootstrapped first
  • voxtype-binThe offline Whisper voice-dictation daemon
  • localsend-binAirDrop-style LAN file sharing
  • nvibrant-binNVIDIA digital vibrance for the pill fader
  • spicetify-cliPatches Spotify for the Canvas widget
  • game-devices-udev, xpadneo-dkmsDualSense/Switch Pro rules and Xbox wireless driver
  • phinger / catppuccin / apple cursorsExtra cursor themes for the Hub picker
  • ttf-fraunces-variableFraunces, the editorial brand serif

The CachyOS layer

On the CachyOS image only. Install from that ISO and a Ryoku box is a CachyOS box.

  • linux-cachyos (+ headers)The optimized kernel, booted by default
  • cachyos-settingsThe sysctl, udev, and systemd tuning
  • ananicy-cpp (+ rules)Auto-nice daemon for a responsive compositor
  • scx-schedsThe sched-ext userspace schedulers
  • proton-cachyos-slrThe CachyOS-tuned Proton for Steam and Lutris
  • cachyos keyring + mirrorlistsTrust and mirrors for ongoing updates

Storage footprint

Measured by the installer to size the root partition.

  • On disk, freshThe base + dev + desktop closure lands at ~13–15 GiB (a little less after Btrfs zstd:1 compression).
  • Root floorThe installer reserves 20 GiB — the extra headroom is for AUR builds, snapshots, and first-launch downloads.
  • Minimum disk32 GiB for a whole-disk install; 2 + 20 + swap GiB of free space to dual-boot alongside another OS.
system/packages/ · release/packages/ryoku-desktop · docs/preinstalled.md
Marble columns and torii gates receding into the dark, dithered to bone

· Install

Two ways in.

01 // ISO

Fresh disk

Download an ISO, boot it, and the guided TUI installer partitions, installs, and wires the whole desktop for you. Both images install fully offline: plain Arch, or CachyOS with its kernel and tuning baked in.

ArchreleasesCachyOSreleases
02 // SHELL

Convert in place

One command turns an existing Arch machine into a Ryoku one: config backup, repo trust, desktop set. Reversible with a generated restore script.

· Tested on

Arch at the core. Run and verified against the shells and spins people already use.

Arch Linuxthe base
CachyOSkernel + repo
Omarchytested
iniRtested
Caelestiatested
Noctaliatested

This is a public beta. It shows its cracks.

Unfinished on purpose, in the open. You are seeing Ryoku while it is still being built, not a frozen release.

BETA · v0.1.0-beta.13tracked live from GitHub
A fractured marble bust, its mend seams catching the light, dithered to bone

Common questions.

What is Ryoku?

Ryoku is a hand-built Arch Linux distribution with a complete, pre-configured Hyprland (Wayland) desktop. It ships the desktop, a guided installer, and the system definition that reproduces it from a single source of truth, so a fresh machine boots straight into a polished, ready-to-use desktop.

Read the manual →

Is Ryoku free and open source?

Yes. Ryoku is free and open source, built on Arch Linux and developed in the open on GitHub. There is no paid tier: you install it, update it, and roll it back with the built-in ryoku command, and the desktop ships as signed packages.

Source on GitHub →

Is Ryoku an Omarchy alternative?

Yes. Ryoku shares Omarchy’s philosophy — an opinionated, keyboard-driven, pre-riced Arch and Hyprland desktop that works on day one — and grew from that lineage, but it ships its own Quickshell UI, the Ryoku Settings control center, a plugin and Extras catalogue, and a reproducible single-source system driven by the ryoku CLI. If you like the Omarchy idea, Ryoku is a close, actively developed alternative.

Omarchy heritage →

How do I install Ryoku?

Download and boot the signed Ryoku ISO, and the guided TUI installer partitions the disk, installs the base system and desktop, and reboots you into Hyprland. Already running Arch? One reversible command converts an existing machine in place.

Install guide →

What hardware does Ryoku need?

Ryoku targets modern 64-bit (x86-64) desktops and laptops with AMD, Intel, or NVIDIA graphics, and the installer detects your GPU and displays automatically. 16 GB of RAM is comfortable, and you can try the whole thing in a virtual machine first.

Hardware notes →

How do I update or roll back Ryoku?

Run ryoku update: it snapshots the system, updates from the signed package repository, re-lays the config, and reloads the desktop. If an update ever misbehaves, ryoku rollback (or a snapshot from the Limine boot menu) restores the previous state.

Updates & rollback →

Know when it's stable.

No newsletter, no drip. Two mails, then your address is gone.

  1. 1× Confirmation the moment you sign up.
  2. 1× One mail when the stable build ships.
  3. 0× Everything after. Your address is erased.

[ notify_once ]

Waitlist

no spam · no tracking · erased after stable