StoaLinux

A Stoic desktop for Arch Linux and CachyOS — Hyprland or niri (Wayland) and a unified dark theme inspired by the ancient world.

"The happiness of your life depends upon the quality of your thoughts." — Marcus Aurelius

---

Why

Most rices start from zero and pile things on until the desktop looks like the person who built it. StoaLinux started the other way: from a complete, working system, with everything not earning its place taken back out. That's the distinction the Stoics drew between the sculptor who adds clay and the one who removes marble — Michelangelo said the statue was already in the stone. A desktop built by subtraction carries fewer opinions than one built by accumulation, because every element that survived had to argue for itself first.

It's also a distinction the Stoics drew about a life. A cluttered desktop and a cluttered mind fail the same test: neither one asked, of each thing it kept, whether it served. Minimalism here isn't an aesthetic — it's the dichotomy of control applied to a window manager. You don't control what a distro ships by default. You do control what stays after you've looked at it honestly. Marble, bronze, parchment, stone: the palette isn't decoration either — it's what's left when you strip a color scheme down to what temples, statues, and manuscripts actually looked like, instead of what's trending on a theme repository this month.

The Memento Mori widget sitting on the desktop is the clearest expression of this. It's not a gimmick — it's premeditatio malorum rendered as a Noctalia desktop widget: a quiet, constant reminder that the hours you're spending configuring a window manager are hours you don't get back, so configure it once, well, and then go do something that isn't configuring a window manager. The Stoic quote on every new shell serves the same purpose from a different angle — not decoration, a nudge, every single time you open a terminal, back toward why you're at the machine at all.

None of this makes StoaLinux a religious project. It's a tool built on the premise that a system which asks why before it asks how ends up smaller, calmer, and easier to actually live inside — and that a Stoic reading a good desktop the same way they'd read a good text: for its restraint, not its feature count.

What it is

StoaLinux is a complete Arch Linux environment — automated installation, a unified dark theme across every app it touches, a settings panel built to make external configuration tools unnecessary, and a family of stoa-* scripts that exist because the alternative was five different tools each solving a fifth of the problem.

Wayland is the only display server — there's no Xorg fallback to maintain, because a fallback path nobody uses is not a feature, it's an unexamined habit. The compositor is your choice of two, Hyprland (dynamic tiling) or niri (scrollable tiling), both driven through one small abstraction layer (stoa-wm) so the scripts are written once. Noctalia handles the bar, launcher, control centre, notifications, clipboard history, wallpapers, and lock screen, themed through the bundled Stoa palette. A 23-panel settings app covers the rest — display, audio, network, VPN, firewall, Bluetooth, disks, system health — so nothing on the system asks you to open three unrelated apps to change one thing.

Highlights, briefly:

• Automated Arch installation, from live ISO or an existing system
• Wayland only, with a choice of Hyprland or niri — the same palette, binds and stoa-* tools in both, behind a single stoa-wm layer instead of two forks
• Noctalia as the shell layer, themed via the Stoa palette, with 10 built-in presets and a custom editor
• A 23-panel settings app that replaces the usual pile of separate config tools
• One dark theme, carried consistently into GTK, Qt, Zed, Neovim, Steam, Calibre, and more
• Pacman pre-transaction snapshots, a boot-time health check, and a compositor version adapter — resilience that doesn't wait for you to notice something broke
• A DFM (Dotfile Manager) GUI for editing configs in place, with backups and rollback
• A living marble screensaver, a Memento Mori widget, and Stoic quotes on every shell — the philosophy isn't bolted onto the system, it's rendered by it

Palette

Marble, bronze, parchment, stone — colors chosen because they're what survives from the ancient world, not because they photograph well. Changeable entirely via Super+S → Theme → Color Palette, with 10 presets and a custom editor if the default doesn't suit you — the point was never that you keep it, only that you consider it first.

Presets: Stoic (default), Nord, Dracula, Gruvbox, Catppuccin Mocha, Tokyo Night, Solarized Dark, Rose Pine, GitHub Dark, Base16 Default

Install

A system you didn't install yourself is a system you don't understand yet. These commands get you there; what you do with it afterward is the part that was always the point.

From live ISO:

curl -LO https://raw.githubusercontent.com/VictorGSchneider/StoaLinux/main/setup/arch-install.sh
chmod +x arch-install.sh && ./arch-install.sh

Existing Arch or CachyOS (CachyOS: install it with its own installer first; arch-install.sh is for the Arch ISO only):

git clone https://github.com/VictorGSchneider/StoaLinux.git
cd StoaLinux && chmod +x setup/post-install.sh && ./setup/post-install.sh

Dotfiles only:

git clone https://github.com/VictorGSchneider/StoaLinux.git
cd StoaLinux && chmod +x install.sh && ./install.sh

post-install.sh asks which compositor to install — Hyprland, niri, or both — and records the choice in ~/.config/stoa/wm. Set STOA_WM=hyprland|niri|both to skip the question. With both installed, switch the default session any time with stoa-wm set niri (or hyprland).

zsh is the default login shell; bash stays as a fallback. The setup scripts wire up both automatically. On a system where they weren't run:

echo 'source ~/StoaLinux/shell/.zshrc'  >> ~/.zshrc
echo 'source ~/StoaLinux/shell/.bashrc' >> ~/.bashrc
chsh -s /bin/zsh   # switch to /bin/bash anytime to fall back

To push your own changes back with stoa-sync, connect the machine to GitHub once: bash setup/connect-github.sh (logs gh in through the browser, makes git use that login, sets your commit name and e-mail, and makes this clone pull with rebase; post-install.sh offers it).

install.sh deploys configs and stoa-* binaries as symlinks, so git pull propagates updates live — no re-installing after every change. Keep the clone at a stable path (e.g. ~/StoaLinux). stoa.conf and the OnlyOffice settings.json are copied instead of linked, because those apps write back into their own config and a symlink would push that back into the repo.

Keybinds

Key	Action	Key	Action
Super+Return	Terminal (Kitty)	Super+Shift+V	Clipboard pin
Super+B	Browser (Brave)	Super+Shift+T	OCR (screen text)
Super+C	Calculator (Qalculate)	Super+Shift+P	Advanced paste
Super+Space	Launcher (Noctalia)	Super+/	Keybinds bar
Super+E	Files (Thunar)	Super+Escape	Lock screen
Super+Shift+E	Files (lf)	Super+Q	Close
Super+N	Monitor (btop)	Super+F	Fullscreen
Super+O	Notes (Obsidian)	Super+R	Resize (HJKL)
Super+S	Settings panel	Super+HJKL	Navigate
Super+W	WinApps	Super+Shift+HJKL	Move window
Super+A	App store	Super+G	Dotfile Manager (DFM)
Super+V	Clipboard history	Super+1-0	Workspaces I–X
Super+Shift+S	Text prediction	Print	Capture (screenshot/record)

Hyprland config is Lua (0.55+ required). Stoa ships config/hypr/hyprland.lua; stoa-doctor will tell you if your Hyprland predates it.

Hyprland or niri

Same keys, same palette, same tools. What differs is the layout model:

	Hyprland	niri
Layout	dwindle tree	windows in columns on an endless strip
Super+H/L, Super+J/K	focus left/right/down/up	focus column left/right, window down/up
Super+Shift+HJKL	move window	move column (H/L) or window within it (J/K)
Super+R	resize mode (HJKL)	cycle the column width; Super+Shift+R the window height; Super+Ctrl+HJKL nudge both
Mouse side buttons	app default (browser back/forward)	scroll the strip one column left/right
Alt+Tab	visual switcher (hyprswitch)	previous window; Super+Tab opens the overview
Blur, minimize	yes	no (niri has neither)
Mirror a monitor (Super+P)	built in	needs wl-mirror (installed by post-install.sh)
Config	config/hypr/hyprland.lua	config/niri/config.kdl (reloads on save)

Live tweaks in stoa-settings (gaps, opacity, pointer and keyboard options applied with hyprctl keyword) are Hyprland-only; under niri the panel points you at config.kdl. Cursor theme and the palette are applied to both. niri takes its render GPU from debug { render-drm-device } rather than the AQ_DRM_DEVICES that stoa-gpu-setup writes for Hyprland, so on a hybrid laptop set that line by hand.

Settings Panel

Everything is configured through stoa-settings (Super+S) on the theory that a setting you have to hunt for across five apps is a setting you'll never actually change. 23 panels, one place:

Panel	Covers
Display / Audio / Equalizer / Night Light	Brightness, resolution, multi-monitor, volume, PipeWire devices, EQ presets, blue light schedule
Keyboard / Mouse & Touchpad	Layouts, repeat rate, RGB (OpenRGB); sensitivity, gestures, DPI profiles
Network / VPN / Firewall / Bluetooth	Wi-Fi, ProtonVPN, nftables rules, device pairing
Hardware / Disks & Storage / Printers	Sensors and components; mount, SMART, benchmark, fsck; CUPS + SANE
Cloud Drive	Google Drive, OneDrive, Dropbox, S3 via rclone
Power / Fan & Performance	Power profiles, fan curves, performance modes, GPU mode — NitroSense-like, for the hardware that needs it
Date & Time / Accessibility	Timezone, locale; cursor size, text scale, animation and opacity controls
Screensaver / Wallpaper / Theme	Living marble animation; wallpaper browser/generator; palette, GTK, icons, cursors, font size
System Health / Maintenance	Doctor report, failed units, security audit; backup, restore, 10-step cleanup, scheduled maintenance

Scripts & Stoatools

A family of small, single-purpose stoa-* tools — each one exists because reaching for a general-purpose app to do one specific thing is its own kind of clutter.

Script	What it does	Stoatool	What it does
stoa-settings	Settings panel (23 panels)	stoa-ocr	Extract text from screen
stoa-store	Package manager	stoa-paste	Paste as UPPER/lower/etc
stoa-fetch	System fetch	stoa-resize	Batch resize images
stoa-walls	Wallpaper generator	stoa-rename	Regex rename + preview
stoa-memento-data	Memento Mori data (desktop widget)	stoa-locksmith	Find + end what's locking a file/folder
stoa-doctor	System health check	stoa-predict	Word + emoji suggestions at the text cursor (input method)
stoa-screensaver	Living marble screensaver	stoa-archive	Compress selection / extract archives
stoa-clipboard	Clipboard + pins
stoa-drive	Cloud drive (rclone)
stoa-firewall	nftables firewall
stoa-winapps	Windows apps (KVM/RDP)
stoa-osd	Volume/brightness OSD
stoa-wm	Compositor control (Hyprland / niri)
stoa-quotes-sync	Fetch quotes online
stoa-gpu-setup	GPU + CPU drivers
stoa-maintain	Backup, restore, cleanup (BRCS)
stoa-history	Prune shell history (secrets, noise, duplicates)
stoa-pkg-snapshot	Package snapshot (pacman hook)
stoa-snapshot	System snapshots (Btrfs + Limine)
stoa-snapshots	Snapshot browser (packages + configs)
dfm	Dotfile Manager (GTK4 GUI)

Apps

The chosen ones — not the biggest name in each category, the one that does its job and gets out of the way.

App	Purpose	App	Purpose
Brave	Browser	btop	Monitor
Obsidian	Notes	Qalculate	Calculator
Kitty	Terminal	Noctalia	Shell, widgets
Zed	Code editor	Neovim	Editor
Zathura	PDF	Calibre	eBooks
mpv	Video/audio	YACReader	Comics
OnlyOffice	Office suite	Enpass	Passwords
Betterbird	Email
imv	Images	lf / Thunar	Files
EasyEffects	Audio equalizer	gammastep	Night light
QEMU/KVM	WinApps (VM)	FreeRDP	Remote desktop
Steam	Gaming (Proton)	GnuPG	Encryption & signing

Theme

A theme that stops at the terminal isn't a theme, it's a wallpaper. The Stoa palette is carried into every app it can reach — GTK 3/4, Qt (via qt5ct/qt6ct), Zed, Neovim, Steam, OnlyOffice, Betterbird, Calibre, YACReader — because a system that looks like two different projects stitched together asks something of your attention that a coherent one doesn't. Icons are Colloid-dark, cursors Colloid, fonts EB Garamond for prose and JetBrains Mono for code.

The whole palette is swappable from Super+S → Theme → Color Palette — 10 presets or a custom editor over 11 core colors — and it propagates to Kitty, GTK, Hyprland, niri, and Noctalia automatically. Reset to Stoic restores the original, untouched.

Under the hood

A few things exist to keep the system honest with itself, without asking you to think about them day to day:

• Package snapshots — every pacman transaction is snapshotted first (~/.config/stoa/pkg-snapshots/, last 20), so "what changed" is always answerable.

• Snapshot browser — stoa-snapshots (Stoa Health → Snapshots → See what's inside) shows each package snapshot as what was upgraded, downgraded, installed and removed — since that snapshot or since the one before — and each config backup as its files, marked same, changed or gone compared with today. Open a file to see the diff or the saved copy, and restore just that one (the current file is kept as a before restore backup first).

• Health check — stoa-doctor runs at login, checks dependencies and services, and notifies you only if something's actually wrong.

• Boot snapshots — setup/enable-limine-snapshots.sh lists every Snapper snapshot of / in the Limine boot menu (limine-snapper-sync), so a bad update is undone by booting the snapshot and running limine-snapper-restore. Needs a Btrfs root and Limine (the default bootloader of arch-install.sh); a 4 GiB boot partition holds several snapshots. It checks all of that before changing anything, backs up each file it edits as *.stoa-bak-<date>, and post-install.sh offers it when the machine qualifies. CachyOS ships this preconfigured, and the script notices. Day to day it lives in the Stoa Health panel (bar icon → Snapshots → System): Enable boot snapshots when it is not set up yet, then Create system snapshot (no password once you let your user snapshot), Restore… and List. The same actions are on the command line as stoa-snapshot status|create|setup|restore|list.

• Login screen — setup/enable-stoa-greetd.sh is the default way in: a real login screen through greetd, Noctalia's own greeter when yay/paru can install it (tuigreet otherwise). It starts Hyprland or niri, whichever ~/.config/stoa/wm names (--wm= to force one), unlocks the keyring with your password, and asks before replacing another display manager such as SDDM. setup/enable-stoa-greeter.sh is the lighter alternative: autologin on tty1, where on Hyprland hyprlock is the password prompt — on niri it means no password, and the script says so. post-install.sh offers both.

• stoa-history — reads your shell history and prunes what stopped earning its place: leaked secrets, /tmp junk, ls/cd noise, stale duplicates. Nothing is written without --apply, and every pass is backed up first (stoa-history restore undoes it).

• Text prediction (Super+Shift+S) — a small floating popup for word and emoji suggestions as you type, because a keystroke you don't have to make is a keystroke you don't have to make.

• DFM (Super+G) — a GTK4 GUI for editing dotfiles in place, with versioned backups, validation, and GitHub sync, so "I broke my config" stops being a reason to dread editing it.

• Checks — bash tests/run.sh runs the same checks CI does: shell linting, config-format validation, and a set of StoaLinux-specific invariants (dead keybinds, pacman hooks pointing nowhere, that kind of thing).

• Vendored upstreams — a couple of stoa-* tools are forks of standalone projects, kept alongside a read-only copy of their upstream under scripts/vendor/ so improvements can flow both ways. See scripts/vendor/README.md.

• Text prediction (Super+Shift+S) — word and emoji suggestions in a popup at the text cursor (↓ to enter, ←/→ to pick, Enter to accept). Languages are ticked in Super+S → Keyboard → Text prediction; their word lists are FrequencyWords (OpenSubtitles 2018, CC BY-SA 4.0), downloaded on demand and ranked by how often each word is used.

License

GPL-3.0