A Stoic desktop for Arch Linux — Hyprland (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
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 in eww: 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.
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.
Hyprland (Wayland) is the compositor, full stop — there's no Xorg fallback to maintain, because a fallback path nobody uses is not a feature, it's an unexamined habit. 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
- Hyprland/Wayland only — one compositor, well maintained, instead of two maintained halfway
- 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, VS Code, Neovim, Steam, Calibre, and more
- Pacman pre-transaction snapshots, a boot-time health check, and a Hyprland 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
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
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.shExisting Arch:
git clone https://github.com/VictorGSchneider/StoaLinux.git
cd StoaLinux && chmod +x setup/post-install.sh && ./setup/post-install.shDotfiles only:
git clone https://github.com/VictorGSchneider/StoaLinux.git
cd StoaLinux && chmod +x install.sh && ./install.shzsh 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 backinstall.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.
| 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-doctorwill tell you if your Hyprland predates it.
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 |
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 | Memento Mori widget | stoa-locksmith | Find + end what's locking a file/folder |
stoa-doctor | System health check | stoa-predict | Text prediction + emoji suggestions |
stoa-capture | Screenshot + recording (eww) | stoa-archive | Compress selection / extract archives |
stoa-screensaver | Living marble screensaver | ||
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-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) | ||
dfm | Dotfile Manager (GTK4 GUI) |
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 | eww | Widgets |
| VS Code | IDE | Neovim | Editor |
| Zathura | Calibre | eBooks | |
| mpv | Video/audio | YACReader | Comics |
| OnlyOffice | Office suite | Enpass | Passwords |
| Betterbird | |||
| imv | Images | lf / Thunar | Files |
| EasyEffects | Audio equalizer | gammastep | Night light |
| QEMU/KVM | WinApps (VM) | FreeRDP | Remote desktop |
| Steam | Gaming (Proton) | GnuPG | Encryption & signing |
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), VS Code, 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, eww, GTK, Hyprland, and Noctalia automatically. Reset to Stoic restores the original, untouched.
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. - Health check —
stoa-doctorruns at login, checks dependencies and services, and notifies you only if something's actually wrong. - Stoa Greeter / Greetd — two optional boot paths straight into a themed lock prompt, no display manager.
setup/enable-stoa-greeter.sh(lighter, hyprlock-based) orsetup/enable-stoa-greetd.sh(heavier, also unlocks your keyring on login). Mutually exclusive;post-install.shoffers the first one interactively. stoa-history— reads your shell history and prunes what stopped earning its place: leaked secrets,/tmpjunk,ls/cdnoise, stale duplicates. Nothing is written without--apply, and every pass is backed up first (stoa-history restoreundoes 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.shruns 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 underscripts/vendor/so improvements can flow both ways. Seescripts/vendor/README.md.
GPL-3.0