Donbox

A Hyprland desktop for Fedora, built around a magnifier: one donbox command for everything the desktop does, themes as directories of small declarative files, plugins that declare what they add in a manifest, and a crash that explains itself to a coding agent.

Donbox takes its shape from Omarchy and departs where this desk does: Fedora rather than Arch, the session configured in Lua through Hyprland's own API, and shell chrome sized for a magnified screen while application text stays at sighted size. It runs one machine well rather than every machine adequately; what makes a host itself lives in one machine.lua.

What it does

• One router. donbox <route> reaches every command in bin/ and every enabled plugin. donbox commands lists the lot, donbox docs writes the man page and the bash, fish and zsh completions from the same # donbox: headers the router routes on.
• A themed desktop. Twenty-three themes live in donbox-themes, pinned by commit in packages.toml. donbox theme set renders every template and restyles the shell, terminal, Neovim, btop, the browsers, superfile, slk and TeamSpeak in one pass; donbox theme pick is a carousel with favourites; donbox theme schedule follows the sun between a theme and its pair.
• A Quickshell shell. Bar, launcher, notifications with clickable actions, OSD, menu, choosers, four lock screen designs (donbox lock design preview <id>), and a pinentry pane that answers gpg with large type.
• Plugins. A plugin.toml declares commands, binds, menu rows, bar widgets, packages, units, theme templates, hooks, migrations and settings; nothing loads undeclared. A repository of plugins/<id>/ directories installs as one pinned collection, and Omarchy plugins convert on the way in.
• Crash diagnosis. A coredump, a failed unit, a Hyprland crash or a kernel panic caught by kdump becomes a notification whose button opens the coding agent with the evidence already gathered.
• The board. donbox board serves the Forgejo tracker as a live kanban and roadmap; the tracker stays the source of truth for what is done and what remains.

Install

Fedora 44 with Hyprland, from a checkout that stays the source of truth:

git clone \
    https://forge.quinlan.cloud/joshquinlan/donbox \
    ~/.local/share/donbox
~/.local/share/donbox/bin/donbox install --dry-run
~/.local/share/donbox/bin/donbox install

Twelve idempotent steps run in order: packages (dnf, COPR, Flatpak, mise, fonts), the session environment, the keyring and pinentry wiring, config links, themed templates, the pinned theme collection, user units, kdump arming, snapper, docs and agent skills. --only <step> narrows to one. Log out and back in so the session reads DONBOX_PATH. Thereafter donbox update brings the checkout, its pins and its packages up in one transcripted run, behind a snapshot when the root is btrfs.

Use

donbox theme pick                choose a theme from the carousel
donbox theme set kanagawa-wave   switch by slug
donbox capture text              read a region onto the clipboard
donbox timer 25m                 a kitchen timer the shell rings
donbox alarm add 07:30 --days mon,tue,wed,thu,fri
donbox launch firefox            raise the window, or start it
donbox network share             this Wi-Fi as a QR code
donbox screentime today          who had the focus today
donbox pkg add btop              install, and record it
donbox migrate                   bring machine state up to date

The keys that matter, from default/hypr/binds.lua: Super+Space launcher, Super+Return terminal, Super+B browser, Super+Alt+T themes, Super+N notifications, Super+P screenshot, Super+Alt+P capture text, Super+Alt+R record, Escape closes the open pane.

Overrides live under ~/.config/donbox: hypr/*.lua, shell.lua, menu.lua, machine.lua, themed/*.tpl, hooks/ and plugins/<id>.lua overlay the defaults of the same name; maps merge, lists replace whole.

Write a plugin

donbox plugin new <id>
donbox plugin validate plugins/<id>
bash plugins/<id>/test/shell.d/<id>-test.sh

The first-party plugins under plugins/ are the reference for every manifest section; default/plugin-template is the scaffold.

Layout

bin/            donbox and donbox-* commands, one per file
lib/            the shared library: packages, theme, plugin,
                crash, install, docs
default/        Lua session, shell layout, menu, templates,
                units, hooks, sounds, plugin template
shell/          Quickshell: shell.qml, Commons, ui, services
plugins/        first-party plugins
install/        the ordered, idempotent install steps
migrations/     <epoch>.sh, run once per user
tools/          vm-dry-run and the theme converter
test/           the shell, qml, lua and python runners
packages.toml   everything the desktop installs, pinned

DONBOX_PATH names the checkout; ~/.config/donbox holds overrides; ~/.local/state/donbox holds rendered state and ledgers. $HOME stays clean.

Develop

./test/shell && ./test/qml && ./test/lua
shellcheck bin/* lib/*.sh lib/*/*.sh

Every script passes shellcheck, behaviour lands with a test, and anything visual is verified on the running shell. Work is tracked on the forge under repo/* labels, read and reordered through donbox board.

Licence

MIT. See LICENCE.