StoaLinux

A Stoic desktop for Arch Linux — Hyprland, i3, and a unified dark theme inspired by the ancient world.

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

---

Marble, bronze, parchment, stone — colors from temples, statues, and manuscripts. EB Garamond as the serif. JetBrains Mono in the terminal. A Stoic quote every time you open a shell. A Memento Mori widget on the desktop reminding you that time is finite.

StoaLinux is a complete Arch Linux environment with automated installation, a unified dark theme across every app, a settings panel that replaces the need for any external configuration tool, and a collection of stoa-* scripts that handle everything from wallpapers to OCR to cloud drives.

This isn't minimalism for aesthetics. It's minimalism by principle: only what serves, stays.

Highlights

• Arch Linux with automated installation (from live ISO or existing Arch)
• Hyprland (Wayland) as the main compositor, i3 as Xorg fallback
• Noctalia Shell (QML on Quickshell) as the bar + quick-settings + notifications, themed via the bundled Stoa color scheme; waybar stays as an optional fallback via STOA_BAR in stoa.conf
• 25-panel settings app via Rofi — display, audio, network, VPN, firewall, Bluetooth, disks, system health, and more
• 10 color presets (Nord, Dracula, Gruvbox, Catppuccin...) + custom color editor applied system-wide
• Unified dark theme across GTK, Qt, Steam, Calibre, YACReader, OnlyOffice, Betterbird, VS Code, Neovim
• Capture toolbar (eww) — screenshot + recording with mode selection, toggle, and delay
• System resilience — pacman pre-transaction snapshots, hyprctl version adapter, health check on boot
• Memento Mori widget (eww), Stoic quotes, and a living marble screensaver
• DFM (Dotfile Manager) — GTK4 GUI to edit dotfiles in-place with smart widgets, backups, and GitHub sync
• Text prediction popup (eww) — system-wide word suggestions + emoji as you type, like Windows text suggestions
• stoa-* scripts for wallpapers, clipboard, OCR, paste, resize, firewall, WinApps, and more

Palette

The default palette is inspired by the ancient world — marble, bronze, parchment, stone. It can be changed entirely via Super+I → Theme → Color Palette, with 10 built-in presets and a custom color editor.

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

Install

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:

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

Shell — zsh is the Stoa default login shell; bash is kept as a fallback. The setup scripts (arch-install.sh / post-install.sh) seed both rc files and chsh into zsh automatically. On an existing system where the setup scripts weren't run, wire it up manually:

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

install.sh deploys configs and stoa-* binaries as symlinks into the repo, so a git pull propagates updates live — no need to re-run the installer after every change. Keep the clone at a stable path (e.g. ~/StoaLinux); if you move it, run install.sh again to refresh the link targets. Two files are deliberately copied instead of linked (stoa.conf and OnlyOffice settings.json) because the apps write to them and a symlink would push your edits 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 (lf)	Super+Escape	Lock screen
Super+Shift+E	Files (Thunar)	Super+Q	Close
Super+N	Monitor (btop)	Super+F	Fullscreen
Super+O	Notes (Obsidian)	Super+R	Resize (HJKL)
Super+M	Memento Mori	Super+HJKL	Navigate
Super+I	Settings panel	Super+Shift+HJKL	Move window
Super+W	WinApps	Super+G	Dotfile Manager (DFM)
Super+A	App store	Super+1-0	Workspaces I–X
Super+V	Clipboard history	Print	Capture (screenshot/record)
Super+Shift+S	Text prediction

Settings Panel

Everything is configured through stoa-settings (Super+I) — no external settings app needed.

Panel	Features
Display	Brightness, resolution, scale, rotation, multi-monitor (extend/mirror)
Audio	Volume, output/input devices (PipeWire)
Equalizer	8 built-in EQ presets + user presets via EasyEffects
Night Light	Blue light filter (2500K–6500K), schedule (manual/sunset/custom)
Keyboard	Layout (12 presets + custom), repeat rate, Caps Lock remap, NumLock, RGB lighting (color, mode, brightness via OpenRGB)
Mouse & Touchpad	Sensitivity, accel, scroll, tap-to-click, 12 configurable gestures, DPI (100–25600), polling rate, DPI profiles
Network	Wi-Fi, saved networks, network info (IP/DNS/gateway/signal)
VPN	ProtonVPN: connect by country, P2P, Secure Core, kill switch
Firewall	nftables: port list, allow/block, service toggle
Bluetooth	Scan, connect, saved devices, forget
Hardware	CPU, GPU, RAM, disks, battery, USB, PCI, sensors, cameras, input
Disks & Storage	Overview, usage analyzer (drill-down), mount/unmount, SMART, benchmark, format, fsck, fstab, cleanup
Printers	CUPS: add/remove printers, print queue, scanners (SANE)
Cloud Drive	Google Drive, OneDrive, Dropbox, S3 via rclone
Power Management	Power profiles, screen off timeout, auto suspend, battery info, fan & performance (NitroSense-like)
Fan & Performance	Fan mode (auto/turbo/silent), fan speed (manual PWM), performance profiles (Eco→Turbo), GPU mode, KB backlight timeout, boot sound, LCD override. Supports: Div Acer Manager Max, acer-predator kernel module, NBFC, generic hwmon
Date & Time	Timezone, NTP, manual time, 12/24h, language & locale
Accessibility	Cursor size, text scale, animations, gaps, opacity, border width
Screensaver	Living marble animation (plasma noise in Stoa palette), idle timeout
Wallpaper	Browse, generate, set custom
Theme	Color palette (10 presets + custom), GTK, icons, cursors, font size
Lock Screen	Lock now, face recognition setup
System Health	Doctor report, services status, failed units, thermals, journal, updates, package snapshots (diff), security audit, config integrity
Maintenance	Backup configs, restore (interactive/bulk), full system cleanup (10-step), dry-run preview, schedule cleanup at boot

Scripts & Stoatools

Script	What it does	Stoatool	What it does
stoa-settings	Settings panel (25 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	See who locks a file
stoa-doctor	System health check	stoa-predict	Text prediction + emoji suggestions
stoa-capture	Screenshot + recording (eww)
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-face	Face unlock (howdy)
stoa-gpu-setup	GPU + CPU drivers
stoa-maintain	Backup, restore, cleanup (BRCS)
stoa-pkg-snapshot	Package snapshot (pacman hook)
dfm	Dotfile Manager (GTK4 GUI)

Apps

App	Purpose	App	Purpose
Brave	Browser	btop	Monitor
Obsidian	Notes	Qalculate	Calculator
Kitty	Terminal	eww	Widgets
VS Code	IDE	Neovim	Editor
Zathura	PDF	Calibre	eBooks
mpv	Video/audio	YACReader	Comics
OnlyOffice	Office suite	Enpass	Passwords
Betterbird	Email	howdy	Face unlock
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

The Stoa theme is applied consistently across:

• GTK 3/4 — stoa-gtk.css with dark palette + EB Garamond
• Qt 5/6 — Fusion dark via qt5ct/qt6ct
• VS Code — full color theme (syntax + UI + terminal ANSI)
• Neovim — stoa.vim colorscheme with treesitter support
• Steam — CSS overlay (libraryroot.custom.css)
• OnlyOffice — custom JSON theme (stoa-onlyoffice.json)
• Betterbird — userChrome/userContent CSS (stoa-betterbird.css)
• Calibre — dark reader with EB Garamond 18pt
• YACReader — full Qt stylesheet
• Div Acer Manager Max — Avalonia AXAML theme (bronze buttons, stone cards, marble text)
• Icons — Colloid-dark
• Cursors — Colloid
• Font — EB Garamond (serif) + JetBrains Mono (mono)

Color Palette Manager

Change the entire color scheme from Super+I → Theme → Color Palette:

• Apply Preset — pick from 10 palettes and apply with one click
• Edit Colors — customize any of the 11 core colors individually via hex input
• View Current Palette — see the active colors at a glance
• Reset to Stoic — restore the default marble/bronze palette

Changes propagate automatically to: Noctalia Shell (via ~/.config/noctalia/colorschemes/Stoa/Stoa.json), Rofi, Waybar, Kitty, eww, GTK 3/4, Hyprland, hyprlock, i3, and colors.sh. Hyprland and Kitty reload live; Noctalia repaints on the next color-scheme selection — other apps take effect on restart.

Stoa Greeter

Boot straight into a hyprlock prompt themed exactly like Super+Esc — no display manager required. Enable it with:

bash setup/enable-stoa-greeter.sh           # enable
bash setup/enable-stoa-greeter.sh --disable # undo

What it wires up:

• systemd autologin on tty1 via drop-in (/etc/systemd/system/getty@tty1.service.d/stoa-autologin.conf)
• .zprofile / .bash_profile sourcing shell/stoa-autostart-hyprland.sh to exec Hyprland when the shell lands on tty1
• exec-once = hyprlock as the first autostart entry in hyprland.conf, so the lock page renders before anything else
• grace = 0 in hyprlock.conf (a non-zero grace would let any keypress in the first N seconds bypass the password — fine for a normal lock, fatal for a greeter)

post-install.sh offers to run it interactively at the end.

Stoa Greetd (alternative — unlocks the keyring on login)

Same idea as the Stoa Greeter, but using greetd + tuigreet themed in bronze on tty1. Because greetd opens a real PAM session, pam_gnome_keyring runs and unlocks the GNOME keyring with the login password — so Brave (and any other libsecret client) stops asking for the keyring password the first time it opens.

bash setup/enable-stoa-greetd.sh           # enable
bash setup/enable-stoa-greetd.sh --disable # undo

What it wires up:

• /etc/greetd/config.toml — tuigreet --time --remember --asterisks --cmd Hyprland themed in the Stoa palette
• /etc/pam.d/greetd — pam_gnome_keyring.so in both auth and session so the keyring destrava sozinho on every login
• greetd.service enabled on boot
• Stoa Greeter teardown — autologin drop-in and .zprofile / .bash_profile hooks are removed automatically (the two flows are mutually exclusive)
• exec-once = hyprlock in hyprland.conf is commented out (greetd already authenticated; locking again would force a double password). --disable restores it.

Pick one or the other:

	Stoa Greeter (hyprlock)	Stoa Greetd (tuigreet)
Visual	hyprlock graphical lockscreen	TUI in tty1, bronze prompt
PAM session	no (auth only)	yes
Keyring unlocks on login	no	yes
Boot weight	lighter (autologin + lock)	a touch heavier (greetd daemon)

System Resilience

• Package snapshots — pacman pre-transaction hook saves pacman -Q before every install/upgrade/remove (~/.config/stoa/pkg-snapshots/, last 20, auto-rotates). Compare snapshots with current state to see exactly what changed.
• Hyprland version adapter — stoa-doctor detects hyprctl output format on boot and all 25+ settings calls adapt automatically via _hyprctl_get().
• Health check — stoa-doctor runs on login, verifies all binary dependencies and services, and notifies via Noctalia Shell (which owns org.freedesktop.Notifications — scripts call notify-send). Full log at ~/.config/stoa/doctor.log.

Vendored upstreams

Some stoa-* scripts are forks of standalone projects and live alongside a read-only copy of their upstream under scripts/vendor/. Pull new upstream commits with:

scripts/vendor/sync-upstream.sh brcs   # updates scripts/vendor/brcs/

The helper does a squashed git subtree pull, then prints a diffstat of the Stoa fork against the refreshed upstream so you can see which hunks are candidates to forward-port. Currently vendored:

• BRCS.sh (upstream) → fork at scripts/stoa-maintain.sh
• DFM (upstream) → directory-based fork at scripts/stoa-dfm/

See scripts/vendor/README.md for the full arrangement and the one-time bootstrap command.

DFM — Dotfile Manager

A GTK4/libadwaita GUI for editing dotfiles in-place — no moving, no centralizing. Launch with Super+G, from the Noctalia launcher, or dfm.

• Smart widgets — auto-generated toggles, sliders, color pickers, and path selectors based on config file content
• Versioned backups — automatic snapshots before every edit, with rollback support
• Syntax validation — JSON, TOML, YAML, INI, shell, Xresources, plus cross-file conflict detection
• GitHub sync — push/pull dotfiles via gh, create repos, share as Gists
• 80+ known configs — shells, window managers, terminals, status bars, editors, and more
• Profile management — switch between configuration sets and built-in templates

install.sh installs the in-tree fork (scripts/stoa-dfm/) as an editable package — pipx install --editable when available, a user venv otherwise — so a git pull on StoaLinux propagates live to the running dfm binary, matching the symlink semantics used for every other stoa-* script. The XDG desktop entry (data/dfm.desktop) is symlinked into ~/.local/share/applications/ so the Noctalia launcher and other app grids pick it up. stoa-doctor flags a missing dfm binary on login.

Text Prediction

System-wide word suggestions and emoji picker, similar to Windows text suggestions. Toggle with Super+Shift+S.

• Word completion — as you type, a floating popup shows up to 5 dictionary-based suggestions (prefix match via /usr/share/dict/words)
• Emoji suggestions — related emojis appear alongside word completions (120+ keyword mappings built-in, extensible via ~/.config/stoa/predict-emojis.json)
• Click to insert — selecting a suggestion erases the typed prefix and inserts the full word or emoji via wtype
• Modifier-aware — ignores keystrokes with Ctrl/Alt/Super (shortcuts don't trigger suggestions)
• eww popup — non-focusable overlay at bottom-center, styled with the Stoa palette
• Multi-keyboard — auto-detects all keyboard devices via evdev

Requires the user to be in the input group (handled automatically by post-install.sh).

License

GPL-3.0