Omarchy Reference — Arch + Hyprland, and a $4/mo cloud build

What Omarchy is

omakase

Omarchy is a complete, opinionated Linux desktop built on vanilla Arch Linux with the Hyprland tiling Wayland compositor. It is not a grab bag of preinstalled packages: every piece — window manager, bar, launcher, terminal, editor, browser, notifications, lock screen, themes — is chosen, configured, and wired together into one coherent system before you first log in.

The word its author uses is omakase — the sushi-bar arrangement where the chef decides and you eat well. You get Arch's rolling packages and Hyprland's animations-and-tiling model with none of the weeks of dotfile archaeology those normally demand. Everything remains plain Arch underneath: change anything you like, it's your machine.

Started by DHH (David Heinemeier Hansson, creator of Ruby on Rails and co-founder of 37signals) in 2025; now stewarded by the Omacom Foundation, launched in 2026 with $10M in funding. Free and open source.

Why you'd use it

the pitch

Arch without the setupa battle-tested Hyprland configuration on day one — the part that normally takes weeks of tinkering is done

Keyboard-firstevery window, workspace, app and menu is a Super chord away; the mouse becomes optional

Beautiful by intent"a beautiful system is a motivating system" is a stated design principle — 19 coordinated themes restyle the whole desktop at once

Terminal-nativeships with Neovim (LazyVim), lazygit, lazydocker, btop and a stack of TUIs as first-class citizens, aimed squarely at developers

Web apps as appsHEY, Basecamp, WhatsApp, YouTube etc. install as windowed Chromium web apps with their own icons

Rolling + curatedpackages come from an Omarchy-curated Arch mirror snapshot, so updates arrive tested against the whole system

Who it fits — honestly

fit check

A good match

Developersthe whole design assumes you live in a terminal and a browser

Tiling-curiousthe gentlest serious introduction to Hyprland that exists

Ex-macOS tinkerersopinionated defaults with escape hatches everywhere

A poor match

Familiarity seekersit deliberately rejects the Windows/macOS desktop metaphor — no dock, no desktop icons, tiling by default

Old hardwareHyprland's animations want a real GPU; x86_64 only, UEFI only, and the ISO wants the whole disk

Set-and-forget usersit's still rolling-release Arch — updates are frequent and occasionally demand attention

The project at a glance

facts

First release	2025 — began as DHH's public config scripts, became a distribution
Current	4.0.1 "quattro" ISO (March 2026 saw 3.x; 4.0 arrived mid-2026)
Install media	~6.8 GB ISO with a guided installer; wipes the target disk
Requirements	x86_64 · UEFI · 4 GB RAM minimum (8 GB recommended) · ~60 GB disk
Boot stack	Limine bootloader · Btrfs root with snapshots · Plymouth splash
Repos	`stable-mirror.omarchy.org` — curated snapshots of the Arch repos + an `[omarchy]` repo
Manual	`omarchy.org/manual` — short, readable, worth an evening

ARM64 is not supported officially (the repo serves x86_64 only), though community ports run it on Apple Silicon VMs and an aarch64 ISO is on the roadmap.

Core desktop

the machinery

piece	role
Hyprland	Compositor / window manager — tiling Wayland with animations; the heart of the system
Waybar	Top bar: workspaces, clock, tray, battery, network
Walker	Launcher — `Super`+`Space` for apps, plus clipboard history and emoji modes
Mako	Notification daemon
SwayOSD	On-screen volume / brightness overlays
Hyprlock / Hypridle	Lock screen and idle management
Hyprshot	Screenshots (region / window / display)
PipeWire	Audio (and screen-share plumbing)

Daily applications

the omakase menu

app	role
Alacritty	Terminal (`Super`+`Return`)
Chromium	Browser, and the engine behind installed web apps
Neovim + LazyVim	Editor, fully configured (`Super`+`N`)
Nautilus	File manager
btop · lazygit · lazydocker	The TUI suite — system monitor, git, Docker
Obsidian · LibreOffice	Notes and documents
Docker	Preinstalled and group-configured
Signal · LocalSend	Messaging and LAN file drop

Install-on-demand helpers exist for VS Code, Zed, Steam, RetroArch, Tailscale, NordVPN and more — see omarchy-install-* in §05.

How it hangs together

config model

Omarchy's config model is a two-layer sandwich: the distribution's defaults live in ~/.local/share/omarchy/ (a git checkout of the omarchy repo), and your overrides live in ~/.config/hypr/ and friends, which source the defaults and then let you append your own lines.

~/.local/share/omarchythe distro itself: defaults, themes, the 284-command bin/

~/.config/hypr/hyprland.confyour Hyprland config — sources omarchy defaults, then your lines win

~/.config/hypr/monitors.confdisplay layout, resolution, scale

~/.config/omarchy/current theme, per-user state

Updates (omarchy-update) git-pull the defaults layer and migrate configs; your override files are left alone.

1 · The ISO

blessed path

Download from omarchy.org, write to USB, boot with UEFI, follow the guided installer. It wipes the whole target disk (Btrfs + Limine + full disk encryption offered) and drops you into the finished desktop in under half an hour.

best forreal hardware you can dedicate — a spare ThinkPad or a Framework is the community's happy path.

2 · A local VM

try before you buy

The ISO boots in VMware/VirtualBox/Parallels on x86; on Apple Silicon the stock ISO won't boot (it's x86-only) but community scripts build it on Arch Linux ARM in UTM/Parallels. Give the VM UEFI firmware, 8 GB RAM, 64 GB disk, and 3D acceleration if offered.

expectsofter animations than bare metal; VM display drivers are the usual trap — the official manual has a VM page.

3 · Script onto existing Arch

adventurous

The pre-ISO install path still exists: on a vanilla Arch box, curl the installer and run it as a normal user with sudo. It swaps in Omarchy's mirror, clones the repo to ~/.local/share/omarchy, and runs the same package/config/login phases the ISO does.

curl -fsSL https://omarchy.org/install | bash

unsupportedUpstream assumes the ISO's Limine + Btrfs layout; on anything else two guard checks fail and hardware-specific steps need skipping. Doable — §07 is the proof — but read §08 first.

Launching

apps

Super Returnterminal (Alacritty)

Super Spaceapp launcher (Walker)

Super Bweb browser

Super Ffile manager

Super NNeovim

Super Tbtop system monitor

Super Dlazydocker

Super Mmusic player

Super OObsidian

Super Gmessenger

Super /password manager

Super Kshow all key bindings

Windows

tiling

Super Wclose window

Super arrowsmove focus between windows

Super Shift arrowsswap window in that direction

Super − / =shrink / expand window

Super Shift Vtoggle floating

Shift F11force full screen

Alt F11full width

Super Jtoggle split direction

Super Ppseudo-tile

Alt Tabcycle windows

Super mouse-dragmove (left) / resize (right) window

Super Backspacetoggle window transparency

Ctrl Alt Deleteclose all windows

Workspaces

1–10

Super 1…0switch to workspace 1–10

Super Shift 1…0move window to that workspace

Super Shift Alt 1…0move it there silently (stay put)

Super Tabnext workspace

Super Shift Tabprevious workspace

Super Ctrl Tabjump back to former workspace

Super Stoggle scratchpad workspace

Super Alt Ssend window to scratchpad

Super Ltoggle workspace layout

Menus & system

omarchy-menu

Super Alt Spacethe Omarchy menu — everything hangs off this

Super Escapesystem menu: lock, suspend, restart, shutdown

Super Ctrl Ccapture menu: screenshot, recording, text extraction

Super Ctrl Hhardware menu

Super Ctrl Otoggles menu (idle, nightlight, notifications…)

Super Shift Ctrl Spacetheme menu

Super Ctrl Spacetheme background menu

Super Shift Spaceshow / hide the top bar

Super Ctrl Vclipboard history (Walker)

Super Ctrl Eemoji picker

Universal clipboard: Super+C/V/X copy/paste/cut in any app — terminal included, no more Ctrl+Shift+C asymmetry.

Staying current

update

omarchy-update is a tool that updates the whole system in one shot: pulls the omarchy repo, runs config migrations, updates system + AUR packages, and offers a restart.

omarchy-updatethe one command — repo, migrations, packages

omarchy-update-availablecheck without applying

omarchy-update-firmwarefwupd firmware pass

omarchy-update-orphan-pkgsclean orphaned packages

omarchy-snapshotBtrfs snapshot (ISO installs) before risky change

omarchy-versioninstalled version (3.8.5 on the cloud box)

Packages & apps

pkg / install

omarchy-pkg-install is a wrapper over pacman/AUR that keeps the curated-mirror model intact; omarchy-install-* scripts add whole optional stacks.

omarchy-pkg-install / removepackages, fuzzy-searchable

omarchy-pkg-aur-installAUR via yay, kept separate on purpose

omarchy-install-vscode · -zed · -helixeditors on demand

omarchy-install-gaming-steam · -retroarch…gaming stacks

omarchy-install-tailscale · -dropbox · -docker-dbsservices

omarchy-webapp-install / removesite → windowed app with icon

omarchy-tui-install / removeterminal apps pinned to the launcher

Look & feel

theme / font

omarchy-theme-list / -setswitch everything at once — see §06

omarchy-theme-install / -removeadd community themes from git URLs

omarchy-theme-bg-nextcycle the theme's wallpapers

omarchy-font-list / -setsystem monospace font

omarchy-branding-screensaverthe terminal screensaver text

Restart / refresh anything

omarchy-restart-*waybar, walker, hypridle, pipewire, wifi, bluetooth…

omarchy-refresh-*re-copy a component's default config over yours (asks first)

System control

toggle / capture

omarchy-toggle-idlecaffeine — stop the screen sleeping

omarchy-toggle-nightlightwarm colour at night

omarchy-toggle-notification-silencingdo-not-disturb

omarchy-capture-screenshotregion screenshot to clipboard

omarchy-capture-screenrecordingscreen recording

omarchy-capture-text-extractionOCR any region of the screen

omarchy-system-lock / -suspend…scripted power states

omarchy-launch-webcam-overlaypicture-in-picture camera for screencasts

The 19 built-ins

omarchy-theme-set

tokyo-nightcatppuccincatppuccin-latteeverforest gruvboxnordkanagawarose-pine etherealflexoki-lighthackermanlumon matte-blackmiasmaosaka-jaderetro-82 ristrettovantablackwhite

lumon is a Severance homage; retro-82 a CRT throwback; flexoki-light, catppuccin-latte and white are the light options. Community themes install by git URL with omarchy-theme-install.

Living with themes

daily use

Super Shift Ctrl Spacetheme menu — pick visually

omarchy-theme-set kanagawasame thing, scripted

Super Ctrl Spacecycle the current theme's wallpapers

omarchy-theme-currentwhat's active

Themes live in ~/.local/share/omarchy/themes/<name>/ — a folder of per-app config fragments plus backgrounds/. Copy one, recolour it, and you've made your own.

Why do this at all

the case

Because trying Omarchy properly normally costs a laptop. The ISO wants a whole disk; a local VM ties up your machine. For $4/month parked you get a persistent, always-reachable Omarchy that survives reboots, keeps its state, and is fast to resurrect from anywhere.

Learn Hyprlandhotkeys and the tiling model transfer 1:1 to a future hardware install

A standing Linux boxit's still full Arch: Docker, dev tools, cron jobs — with a desktop when you want one

Zero hardware riskterminate it and it never happened

honestySoftware rendering over VNC is fine for terminals, editing and window management — it is not the buttery 120 fps of Omarchy on a real GPU, and video/gaming are out.

What it costs

the math

item	cost
50 GB gp3 EBS disk	$4.00/mo — the only always-on cost
t3a.medium, running	$0.0376/hr (2 vCPU, 4 GB, us-east-1)
parked (stopped)	instance $0 — disk only
2 h/day habit	≈ $6.30/mo all-in
left on 24/7	≈ $31/mo — don't; the wrapper makes parking painless

No Elastic IP (that's $3.6/mo for nothing) — the wrapper asks AWS for the current address each connect. Feeling cramped? A stop → resize to t3a.large (8 GB) → start takes two minutes and doubles the hourly rate only while you use it.

The recipe

7 steps

Condensed; every step is expanded in the cards that follow.

# 1 · launch a community Arch AMI (x86_64, EBS-backed) aws ec2 describe-images \ --filters 'Name=name,Values=arch-linux-std-hvm-*'find the newest; they rebuild twice a month # 2 · t3a.medium · 50 GB gp3 · security group = port 22 only # 3 · fix the Arch keyring ritual, full pacman -Syu, add your user # 4 · run the Omarchy installer (auto-answer its two guard prompts) curl -fsSL https://omarchy.org/install | bash≈ 25 min, ~20 GB # 5 · virtual display + software GL echo vkms | sudo tee /etc/modules-load.d/vkms.confa DRM device with no silicon behind it # 6 · headless session: systemd user service runs start-hyprland loginctl enable-linger $USERdesktop up whenever the box is # 7 · wayvnc on 127.0.0.1:5900, reach it over an SSH tunnel ssh -L 5901:localhost:5900 user@boxthen a VNC viewer at localhost:5901

The hard part: no GPU exists

vkms + llvmpipe

A cheap EC2 instance has no GPU and no /dev/dri at all, and Hyprland's backend (Aquamarine) refuses to start without a DRM device. Three pieces fix it:

vkmsthe kernel's virtual KMS module — a real DRM display device with no hardware behind it, made for exactly this

llvmpipeMesa's software OpenGL — the CPU becomes the GPU (LIBGL_ALWAYS_SOFTWARE=1)

a 40-line EGL shimAquamarine matches EGL devices to DRM nodes by name; Mesa's software device reports none, so no match is ever found. An LD_PRELOAD shim answers the name query with the vkms node — and the whole stack lights up

Session env that makes it fly: AQ_DRM_DEVICES=/dev/dri/card0 · LIBSEAT_BACKEND=noop · WLR_LIBINPUT_NO_DEVICES=1 · LIBGL_ALWAYS_SOFTWARE=1 · LD_PRELOAD=…/eglshim.so. Nested-compositor routes (sway/Weston hosting Hyprland) all dead-end on protocol-version mismatches; the shim route is smaller and survives updates.

The one-command feel

wrapper

A small shell wrapper gives the cloud desktop the ergonomics of an app. The pattern (trimmed):

# find the instance by Name tag — nothing hardcoded iid=$(aws ec2 describe-instances \ --filters "Name=tag:Name,Values=omarchy-server" \ --query "…InstanceId" --output text) # start if parked, wait, learn today's IP aws ec2 start-instances --instance-ids $iid aws ec2 wait instance-running --instance-ids $iid # tunnel + the Mac's built-in VNC client ssh -f -N -L 5901:localhost:5900 user@$ip open -a TigerVNC --args localhost:5901the viewer opens the desktop

Sub-commands worth having: ssh (plain shell), stop (park it), status. Total wrapper: ~60 lines of zsh.

What it's like to use

verdict

Over a home connection the desktop is entirely usable for its purpose: terminals are crisp, Walker pops instantly, workspace switches feel native because VNC only ships the pixels that change. Waybar, themes, notifications — the whole Omarchy personality is intact.

Greatterminals, Neovim, lazygit, window management, learning the hotkeys

Finebrowsing docs, Obsidian, theme hopping

Skipvideo, animation-heavy sites, anything called gaming

4 GB RAM runs the desktop plus a real terminal workload comfortably; heavy browser tabs are what push it — resize to t3a.large for that.

The firewall lockout

read before first boot

lockoutOmarchy's first desktop login runs a firewall setup that does ufw default deny incoming and ufw --force enable — with no SSH rule. On a laptop that's sensible hardening. On a remote server it is the last thing your session ever sees.

sudo ufw allow 22/tcprun it right after install, before Hyprland ever starts — rules persist while ufw is disabled

Guards + auto-retry = infinite loop

installer

The installer's preflight demands Limine and a Btrfs root; a cloud Arch image has GRUB and ext4, so two guards fail, each asking "Proceed anyway?" via gum confirm. Fine — until you script the answers: the installer's error handler also asks "retry?", and a blanket auto-yes turned one deterministic failure into ~70 nested installer processes re-running from the top forever.

Auto-answer the two guards only; let real errors stop the run. And skip the Limine/Snapper/Plymouth steps entirely on a GRUB box — they're boot cosmetics a server doesn't need.

mkinitcpio hooks left disabled

silent time bomb

The installer disables the mkinitcpio pacman hooks during package installation (a legitimate speed trick) and re-enables them in a Limine-only step. Skip that step and every future kernel update installs a kernel without rebuilding the initramfs — the box is fine until its next reboot, then unbootable.

ls /usr/share/libalpm/hooks/ | grep disabledif mkinitcpio hooks show up here, rename them back and run sudo mkinitcpio -P

Arch-image rituals

first contact

stale keyringfresh image + pacman -Syu → "required key missing". Fix: pacman-key --init && pacman-key --populate archlinux, update archlinux-keyring first, then upgrade

root device namingthe AMI's root is /dev/sda1 — a block-device mapping for /dev/xvda quietly creates a second disk instead of growing the root

8 GB default diskgrow the volume, then growpart + resize2fs online — no reboot needed

mirrorlist replacedthe Omarchy installer points all of pacman at its curated mirror — intentional, but know your box now tracks Omarchy's snapshot cadence

Headless quirks

worth knowing

SDDM wants a seatdisable the login manager; a systemd user service + loginctl enable-linger owns the session instead

use start-hyprlandbare Hyprland misses Omarchy's session env — first symptom: "command not found: omarchy-…" toasts

PATH in servicessystemd units don't read your shell profile; add ~/.local/share/omarchy/bin to the service's PATH

vkms wakes at 1024×768pin it: monitor = Virtual-1,1920x1080@60,0x0,1 in monitors.conf

Apple’s VNC client refusesmacOS Screen Sharing cannot join a passwordless VNC server (and barely tolerates third-party auth) — use TigerVNC as the viewer, or give wayvnc auth with relax_encryption=true, the option that enables the Apple DH security type it speaks

the lock screen strikeshypridle locks the idle desktop and a fresh cloud user has no password, so hyprlock can never be satisfied — set one (chpasswd) and disable idle-locking on a tunnel-only box (pkill -x hypridle, persisted with an exec-once)

pkill self-matchesover ssh, pkill -f patterns can match your own remote shell and cut the branch you sit on — bracket a letter: pkill -f "swa[y]"

Daily

musts

omarchy-updatekeep the whole system current

omarchy-theme-set NAMErestyle everything

omarchy-pkg-installadd software the omakase way

omarchy-menuthe everything-menu from a shell

omarchy-versionwhat build am I on

pacman -Q | wc -lhow deep the rabbit hole goes

Hyprland introspection

hyprctl

hyprctl monitorsoutputs, modes, scale

hyprctl clientsevery window and its workspace

hyprctl keyword monitor …change display config live

hyprctl dispatch exec APPlaunch inside the session from ssh

hyprctl reloadre-read hyprland.conf

From a plain ssh shell first: export HYPRLAND_INSTANCE_SIGNATURE=$(ls -t $XDG_RUNTIME_DIR/hypr | head -1)

The headless session

cloud box

systemctl --user status omarchy-headlessis the desktop up

systemctl --user restart omarchy-headlessbounce the session

journalctl --user -u omarchy-headless -ewhy it isn't

ss -tln | grep 5900wayvnc listening?

grim shot.pngscreenshot the headless desktop from ssh

From the laptop

aws + tunnel

aws ec2 start-instances / stop-instanceswake and park

aws ec2 wait instance-runningblock until ready

ssh -f -N -L 5901:localhost:5900 …the tunnel, backgrounded

open -a TigerVNC --args localhost:5901TigerVNC viewer (brew install --cask tigervnc-viewer)

aws ce get-cost-and-usage …trust, but verify the $4

Omarchy the opinionated Arch + Hyprland desktop, end to end

01 · What & Why

A good match

A poor match

02 · The Stack

03 · Getting It

04 · Hotkeys

05 · The Omarchy CLI

Restart / refresh anything

06 · Themes

07 · The Cloud Build — Omarchy on EC2 for $4/mo

08 · Traps

09 · Command Index