A Hyprland desktop,
published as configuration.

The card

The material is taken from Quickshell rather than from the bar: a rofi menu is a large centred card, so the reference is the Super+K keybind overlay — 86% base, a 1 px ring, radius 18, and a gradient with a faint top stop tinted toward the tab accent, a transparent middle and a crust bottom.

The input is recessed rather than raised: it is the only widget darker than the surface it sits on. The selected row uses the active-workspace treatment, a solid accent with base-coloured text.

Up / Down

Move the selection

Escape

Close, as does a click outside the card

The frost comes from the rofi-glass layer rule in hyprland.conf, with the same ignore_alpha as the bar’s, not from the alpha itself. Every widget below the window is transparent so the window alpha is applied once instead of compounding per nested widget.

Seven tabs, seven processes

Each tab has an accent, a glyph and a placeholder, passed to its rofi as a -theme-str: the selection fill, the lit tab, the input glyph, the well’s ring and the card’s top gradient stop all take the same colour.

• appssapphire
• windowsmauve
• filespeach
• gamesgreen
• settingsyellow
• runred
• sshteal

Tab

Next tab; also Shift+Right and Ctrl+Tab

Shift+Tab

Previous tab

Click a tab

Switch directly to it

Switching starts the next tab’s rofi first and polls hyprctl layers until that pid is listed with a non-zero size and full alpha, plus one further frame, before the current process exits, so the card is never absent from the screen. Each process uses a pid file named for its own pid, because two are mapped during the handover.

Prefix matching, and unmatched input

Matching is prefix: each token must begin a word, so stea, disc and chr resolve to single entries. Application entries match on name and generic name only, never on Exec, whose command lines contain unrelated words. The trade-off is substring search: code does not match VSCodium.

Entries are ordered by launch count. Input that matches no row is passed to bin/dispatch on Return, which executes the line if its first word is a command on $PATH and otherwise opens it as a SearXNG query.

Type

Filter by word prefix

Return

Launch the selected row, or dispatch the typed text

Tab lists are cached, keyed on the modification times of their sources, so switching does not re-read hundreds of desktop entries. Launch counts are applied after the cache rather than stored in it.

Windows

Mapped Hyprland windows, sorted by workspace so the list order matches the workspace strip. Special workspaces have negative ids and therefore sort first.

Return

Focus the window by the address returned in ROFI_INFO

rofi’s built-in window mode uses EWMH over xcb, which is unavailable on Wayland, so it returns an empty list. hyprctl clients provides the same data and includes special workspaces.

Files

Thunar sidebar bookmarks first, reused with their labels, then every cd target in the shell history ranked by frequency. Project directories are usually outside $HOME and would not appear in any other rofi mode.

Return

Open it in Thunar

Alt+Return

Open a kitty in that directory

Alt+c

Open it in VSCodium

The key hint is placed at the right end of the input row; as a separate message line it made this tab 20 px taller than the others. Paths on autofs mounts are not stat()ed, since that would trigger the mount and can block on a sleeping server.

Games

One list for every installed game: Steam from the app manifests in each library, Lutris from a cached listing, and desktop entries with Categories=Game. Each group is ordered by last-played time. In the apps tab these entries dominated the launch-count ordering.

Return

Launch it through its own launcher

lutris -l -j starts a Python runtime and is too slow to run while the list is being drawn, so it is refreshed in the background at most once a day.

The settings board

Toggles that otherwise live in bar modules or keybinds: audio output, colour temperature, the bar’s glass, performance mode, the VPN, and the session actions. Each row shows its current state, and selecting one redraws the list instead of closing, so several can be changed in one invocation.

Return

Apply it; the row updates in place

Reboot / Power off

Confirmed on a second list

State is not reimplemented here: the audio, nightlight and glass rows call the same helper scripts the bar’s click handlers call. Tab keys are handled before the selected row is read, so switching tabs cannot apply a toggle.

Run and ssh

run lists every executable on $PATH, ranked by this tab’s launch counts and then by the shell history: the first word of each command, and the word following sudo. ssh lists Host entries from ~/.ssh/config plus plain names from known_hosts, most-used first.

Return

run: detached · ssh: in kitty

Alt+Return

run: in kitty with --hold, so output remains after exit

These replace rofi’s built-in run and ssh modes: in rofi 2.0 a custom key inside a built-in mode is a mode switch rather than an exit, so with one mode per process Tab only reloaded the same tab.

Fixed geometry

680 px wide, with the list reserving nine rows including empty ones rather than shrinking to the match count. No widget in the stack appears or disappears, so switching tabs or typing does not move the card.

Width

680 px, every tab

Rows

9, fixed height

In .rasi, one property per line: the lexer takes a string from the first quote on a line to the last, so two quoted properties on one line parse as a single value.

The websearch and clipboard menus

SUPER + ALT + S is the same card with the list and tab bar removed: a single-line SearXNG prompt that keeps the mauve focus ring, since the input is the entire menu. SUPER + SHIFT + V is the cliphist picker: 800 px, twelve rows, no icons, fuzzy matching, since copied text is recalled in fragments.

Websearch

Return opens the results in a floating browser window, 1400 × 900, centred

Clipboard

Return decodes the entry back onto the clipboard

Floating is applied by window address after the fact: every window of the browser shares one app_id, so a window rule would float all of them. The script records the existing addresses, opens the search, and floats the one that is new.

The toast

Toasts are 520 px wide with a 48 px icon, drawn on the overlay layer 6 px from the top-right corner, below the bar's exclusive zone. The material is the bar's: a vertical gradient, a 1 px ring, no border.

Urgency tints the rim rather than the fill — red at 55% for critical, green at 30% for low — so the palette carries the state and the material stays constant.

Timeouts

7 s normal, 5 s low, and 0 for critical, which does not expire on its own

Images

image-visibility: when-available, so a screenshot notification uses the shot as its icon

Click

The body activates the notification's default action; the sidebar keeps it afterwards

Restyling swaync means matching the default stylesheet's specificity exactly: a bare .notification selector loses to the shipped .notification-row .notification-background .notification.

Cards that are replaced in place

The download tool has no terminal of its own. One card is created when a job starts and replaced under the same notification id as it runs: a progress bar while the download runs, again while it transcodes, and finally an actionable card with Open folder, Copy path and a Discord-sized re-encode.

A screenshot notification carries the image as its icon, with buttons to reveal the folder or copy the path. A failed unit offers its journal.

Replace id

The helper owns the D-Bus plumbing and the id bookkeeping, so the card never stacks up

Heartbeat

swaync ignores expire_timeout on replacement, so the helper re-sends to keep the card alive

Buttons

A listener process runs the action the button names

Three producers here treat a notification as a surface to act on rather than a message to read; everything else uses the default path.

Inline replies, and the code button that is off

Inline replies are enabled, so a reply box appears wherever the sender offers one.

The 2FA action is disabled. swaync scans notification bodies for code-like numbers and cannot distinguish a one-time code from a year, so every notification carrying a date grew a COPY "2026" button. The false positives were constant and real codes are rare, so the feature is off rather than filtered.

Inline replies

On

2FA action

Off, with the reason recorded in the configuration

Both settings are per-daemon, not per-application: there is no way to enable the code button for the senders that get it right.

The sidebar

The bar's bell module toggles the control centre; Escape closes it. It is 440 px wide with 6 px margins, slides in over 180 ms, and carries three widgets: the title row with Clear all, the do-not-disturb switch, and the notification list.

Its height is fit-to-content, which requires two settings together: fit-to-screen: false and vexpand: false on the notifications widget. Without the second, the list fills the window and pins the panel open whatever the height says.

Bell click

Toggle the sidebar

Bell right-click

Do not disturb; new notifications go to the list without popping

Bell middle-click

Clear the list

Emptied, the panel collapses to its title row. The compositor still caps it at monitor height, past which the list scrolls.

Which workspace lights

A notification from a window on an unfocused workspace lights that workspace's tab in the bar. Resolving which workspace is mostly automatic: the daemon takes the notification's sender-pid hint and walks up /proc until it reaches a process that owns a window.

Exactly one workspace lights per notification even when several windows match, because the bus names an application rather than a window: the daemon takes that application's most recently focused off-screen window.

Fallback map

For senders that pass no pid, or notify from a helper whose ancestry leads nowhere near their window

Ignore list

Senders that should never light a workspace; the notification still arrives, and clicking it still jumps to the window

Clearing

Focusing the workspace

The light is driven by a file the daemon writes, not by the compositor: Hyprland's own urgency flag does not survive the round trip from the notification bus.

Two things the configuration cannot say plainly

swaync parses with json-glib, which rejects // line comments and then falls back to defaults — a configuration that looks correct and does nothing. The notes therefore live in a "//" key whose value is an array of strings.

Only one daemon can own the notification bus name. It is started by D-Bus activation, never from exec-once as well: a second copy fails at every login with An instance is already running.

Comments

A "//" key, kept in the file

Starting it

D-Bus activation only

The vestigial unit

A mako unit is kept deliberately: the ordering of its activation file is what let it take the bus name once

The bell module keeps a working fallback path for that other daemon for the same reason, so it never renders blank whichever one is installed.

A snapshot every 60 seconds

A timer writes a snapshot every 60 seconds, and a shutdown unit writes one more on the way out. Each window contributes its class, workspace, geometry, group membership and the command line that produced it; for a terminal, its working directory and foreground program as well.

Snapshots are written with fsync and replace the file rather than rewriting it in place, so a power cut cannot leave a truncated one. The previous snapshot is kept beside it and the last 40 in a history directory.

save

Every 60 s on a timer, and at logout

show / status

What the current snapshot holds, and whether restore is enabled

list

The history, newest first

A snapshot is cheap to take and expensive to miss, which is why the interval is short and the write is atomic rather than clever.

What an unclean shutdown looks like

The shutdown unit clears a clean-exit marker when the session starts and writes it again only if its final save succeeded. A clean logout therefore ends with the marker present; a crash, an OOM kill or a power cut ends without it.

With the marker present, the last snapshot is restored, including whatever was deliberately closed just before logging out. Without it, the restore looks back over the last 15 minutes.

Marker present

Restore the last snapshot

Marker absent

Compare the last 15 minutes of history

Lost > 40% of windows

Restore the fullest snapshot in that window instead

The failure being guarded against is a snapshot taken while the session was already collapsing, which is worse than one taken a few minutes earlier.

Putting the windows back

The compositor runs hypr-session restore --once --if-enabled --delay 6 at login. The delay lets the bar, the notification daemon and the portal come up first.

Terminals return at their old working directory running their old foreground program, wrapped so the shell survives that program exiting. Coding-agent windows return as a resume of their own conversation, matched newest-first so two windows in one directory never resume the same one. GUI applications launch from their desktop entry where there is one, so wrappers still apply.

Matching

By window address, never by title or PID

Placement

Workspace and geometry from the snapshot

--strategy

latest, best or auto

Titles change while a program runs and PIDs are reused, so both are useless as identity; the address is stable for the lifetime of the window.

Choosing which snapshot to restore

The history holds the last 40 snapshots. After an unclean shutdown the restore compares the recent ones by how many windows they held, and prefers the fullest in the last 15 minutes over a final snapshot that caught the session mid-collapse.

Attempts against a snapshot are counted. After two unfinished tries that snapshot is skipped, so a restore that keeps killing the session cannot trap it in a loop; the log prints the command to force it by hand.

auto

The default: latest if clean, fullest-recent if not

latest

Always the newest snapshot

best

Always the fullest in the window

The counter is the important part: an automatic restore that cannot be escaped is worse than no automatic restore.

What does not come back

Unsaved buffers and scrollback are gone. Window groups are not rebuilt; their members return as separate windows. Browser tabs are the browser’s own business, and the tool only moves those windows back to their workspace by title, leaving alone any window whose title has drifted too far to match.

Everything in ignore_classes is skipped because the compositor already starts it: the bar, the notification daemon, the launcher, the portal and the tray applets.

command_blocklist

Refuses to re-run sudo, doas, rm, dd, mkfs, shutdown, reboot, systemctl, pacman, poweroff

Why

A snapshot is a list of command lines that will be executed at the next login

The blocklist is a refusal to execute, not a filter on what is saved: the snapshot still records what was running.

One palette, named the same everywhere

The surface tokens and the fourteen accents are the same values in the QML theme singleton, the launcher’s colour file, the notification stylesheet and the compositor configuration, under the same names, so a colour can be traced from one file to the next.

The accent order is not arbitrary either: it is the sequence the bar assigns to workspaces by position, and the same sequence the daemon writes into the compositor’s group bars.

Surfaces

base, mantle, crust, surface0–2

Text

text, subtext1–0, overlay2–0

Accents

Fourteen, in position order

Where a value has a name in the theme singleton, the other files quote that name in a comment rather than repeating the hex alone.

Every toolkit reads it

GTK 3 and 4, Qt 5 and 6, the terminal, the TUIs, the launcher, the bars, the lock screen and the shell.

GTK uses the Catppuccin Mocha theme with Papirus icons; Qt goes through qt5ct and qt6ct, with dialogs from the desktop portal. The compositor exports GTK_THEME so applications it launches pick the theme up, and QT_QPA_PLATFORM is set to prefer Wayland with X11 as the fallback.

GTK_THEME

Exported by the compositor

QT_QPA_PLATFORMTHEME

qt5ct

QT_QPA_PLATFORM

wayland;xcb

Folder colours are patched to match, and one standalone helper recolours a specific tree; it is not vendored here because nothing else calls it.

Three mechanisms have to agree

Nothing is frosted by itself. The surface has to be translucent, the compositor has to blur what is behind it, and the blur has to be allowed to apply to that surface.

Windows are covered by the compositor’s own blur. Layer-shell surfaces each need an explicit rule: the bar, its relocated copy, the launcher, both notification namespaces and the update panel. ignore_alpha has to sit below the surface’s own alpha, or the blur is skipped as though the surface were opaque.

rounding

8, with a power of 3.0 — a squircle, not a circular arc

blur

size 8, 3 passes

vibrancy

0.22, so the backdrop keeps its colour instead of washing grey

noise

0.02, which is what makes it frosted rather than smeared

The terminal sets its own background opacity so glyphs stay opaque; GTK applications have no equivalent setting, so one is faded whole by a window rule instead.

Values that are shared on purpose

A radius of 10 px appears in three unrelated files — the bar pill, the group-bar tab and the dock tiles — and the compositor’s inner gap is reused as the group bar’s own. Where a value is a match rather than a coincidence, the configuration says so in a comment.

The typeface is one Nerd Font cut throughout, in the no-ligature variant: terminal, bar, group bar, GTK and Qt. Emoji fall back to a colour font, and the terminal maps them to half width so they do not break column alignment in TUIs.

Radius

10 px, in three files that reference each other

Font

One cut, everywhere

Cursor

One built theme, declared in four places because four consumers read four different variables

The comments matter more than the values: without them the next person changes one of the three and wonders why the desktop looks subtly wrong.

The dry run is the default

Run with no arguments, the installer writes nothing and prints every file it would place, where it would go, and whether it would be new or replace something.

It writes into the home directory and nowhere else. It installs no packages, builds nothing and enables no units.

./install.sh

Dry run

--apply

Write the files

--apply config

One section only: config, scripts, bin or units

Running it as root is refused outright: it writes into $HOME, and the wrong $HOME is a slow mess to undo.

Four sections, four destinations

The published tree is laid out as four sections, each with exactly one destination: configuration, scripts, binaries and systemd user units.

Files are placed one at a time, so unrelated files already in a destination are left alone, and a single section can be adopted on its own.

config

→ ~/.config

scripts

→ ~/.scripts

bin

→ ~/.local/bin

units

→ ~/.config/systemd/user

Adopting one part — the bars, or just the launcher — is a supported operation rather than a manual copy, which is the main reason the sections exist.

What --apply changes

Anything it replaces is copied into a timestamped backup directory first, so the previous state is recoverable file by file.

Two placeholders are rewritten on the way in: the placeholder home directory becomes yours, and the placeholder account name in the polkit rule becomes yours. Text files are rewritten; binary files are copied through untouched.

Backups

~/.vaporos-backup/<timestamp>/

Rewrites

Placeholder home and account name

Counters

Written, replaced and skipped, printed at the end

The placeholders exist because the real values identify the machine, and are removed by the export; without the rewrite, half the keybinds would point at a directory that does not exist.

The steps it refuses to take

It finishes by printing what it has deliberately not done: installing the package list, building the Rust daemon, enabling the units, and one optional polkit rule for the power menu.

Each of those is a decision about your machine rather than about the configuration, and each is a one-line command printed in the order it should be run.

Packages

From the published package list

Build

cargo build --release for the state daemon

Units

Enable only the ones you want

polkit

Optional, for a password-free power menu

An installer that enables units is an installer that starts processes on a machine it knows nothing about.

The one thing that cannot adapt

Monitor names are hardcoded, as they are in any Hyprland configuration. The four places that name them are listed in the documentation in the order they will cause problems: the compositor’s monitor block, the bar’s per-output module rules, the second strip’s output, and the wallpaper daemon.

Everything else adapts at runtime or is rewritten by the installer.

Read first

docs/adapting.md

Then

docs/keybinds.md for the full bind list

A single-machine configuration published as-is has exactly one class of value that cannot be derived from the running system, and this is it.

A file is published only if it is named

The repository this is exported from holds one machine’s entire state — system files, package sets, monitor EDIDs, mount points, and a set of private services — and is not public.

The export copies out only what its allowlist names, so anything new is absent by default. A missing entry costs a feature; the opposite default would cost a disclosure.

Published

Named by the allowlist

Absent

Everything else, including anything added since

Absent-by-default is the only arrangement where forgetting to update the export is a visible bug rather than a silent leak.

What cannot be omitted is rewritten

Some values cannot be dropped without breaking the file. A home directory has to be some path, and a polkit rule has to name some account.

Those are rewritten to placeholders on the way out, and the installer substitutes local values on the way in. The rewrites are mechanical and enumerated; no prose is reworded to obscure anything.

Home directory

A placeholder path

Account name

A placeholder user in the polkit rule

Rewriting is limited to values that must exist for a file to work. Anything else that would need rewording is dropped whole instead.

The gate fails the build

Every output file is searched for the account name, the domains, the host names, address literals and key material — the categories that turn a configuration into an identification of a machine.

One match deletes the output tree and exits non-zero, so an export that leaks cannot be committed by accident.

Scope

Every file in the built tree, text and metadata

On a match

Delete the output, exit non-zero

On success

The tree is publishable as-is

The gate runs against the built output rather than the source, so it also catches anything a scrub rule failed to rewrite.

Prose is where configurations leak

Pages describing only that machine are not published at all. Paragraphs naming private infrastructure are removed whole from the pages that are, together with the code examples beneath them, rather than reworded.

The cost is a few code paths that are inert in the export: a module reads a list of self-hosted applications that is not published, finds nothing, and shows no icons. The reader is kept rather than deleted, because removing it would mean rewriting the modules that call it.

Removed

Whole pages, whole paragraphs

Never

Edits inside a paragraph to make it safe

Inert

Documented where it happens

The sentence explaining why a setting exists is usually the sentence that names the machine, which is why the rule is removal rather than rewriting.