Boot the ISO, answer four questions, reboot into a working desktop.
The live image auto-launches Calamares. It lays down a btrfs pool with a proper subvolume layout, unpacks the system, creates your user, and wires the bootloader with the exact sequence that has been verified to boot.
@ @home @snapshots @log @cache, all noatime,compress=zstd. Snapper watches root only, so a rollback never drags your home directory back with it.
snapper + snap-pac take a pre and post snapshot around every pacman transaction. grub-btrfs adds each to the boot menu.
Optional LUKS on the installer's erase-disk page, with the matching cryptsetup, mkinitcpio, and GRUB wiring so it actually boots.
Self-signed via sbctl. Keys enroll automatically when the firmware is in Setup Mode; skipped cleanly otherwise.
greetd plus breadgreet under cage, then the Hyprland session. Plymouth shows the BOS logo on a black background.
Every bread tool is baked into /usr/local at build time from a version-pinned lockfile, verified against a signed index. Nothing is fetched during install.
Around fifteen native tools, baked in and already on PATH.
Each is its own project with its own release cadence, distributed by the
bakery package manager and baked into the image so a fresh install
has all of them with no round-trip. Most are zero-config on first boot.
Reactive automation daemon. Normalizes hardware, compositor, power, network, and Bluetooth signals into semantic events dispatched to Lua modules.
Status bar and notification daemon in one process: workspaces, clock, system stats, tray, OSDs. No waybar, no dunst.
Application launcher with fuzzy search and per-context results.
Idle lock screen, and breadgreet the login greeter: one visual identity from boot to lock.
The shared palette engine every bread app renders through. Fixed dark base, accent slots follow the wallpaper.
Quick-capture scratchpad with model-assisted classification, reminders, and optional CalDAV sync.
The fuller notes manager view. Ships from the same package as breadpad.
Clipboard history: a background daemon records, a GTK4 popup browses.
Semantic system-wide search. Embeds locally, CPU / ROCm / CUDA backend configurable.
Onboarding and in-session help: searchable guides, keybind viewer, troubleshooting wizard.
Location-aware Wi-Fi profile state machine with optional Tailscale exit-node control.
Sets the wallpaper, derives the pywal accent palette from it, reloads every themed app.
TUI monitor layout manager: resolution, position, scaling, mirroring, live via hyprctl.
Screenshot tool wrapping grim, slurp, and wl-copy with multi-monitor-safe region select.
The ecosystem's package manager. Installs, updates, and tracks bread binaries and versions independently of pacman.
Tauri 2 and Svelte control panel: live system state and control, plus non-destructive config editing for every app here.
The desktop responds to what the machine is doing.
The difference between BOS and an Arch install with someone's dotfiles is
bread: a daemon that turns udev, Hyprland, power, network, and
Bluetooth events into a single semantic stream, and dispatches it to small
Lua modules in ~/.config/bread/. Apps talk to each other over the
same bus with a bread.command.<app>.<verb> convention.
local M = bread.module({ name = "dock", version = "1.0.0" }) function M.on_load() -- an external display was plugged in: run the docked layout bread.on("bread.hyprland.monitor.connected", function() bread.exec("~/.config/bread/scripts/dock.sh") bread.notify("Docked", { urgency = "low" }) end) -- battery got low and we are not plugged in: dim the screen bread.on("bread.power.battery.low", function(event) if not bread.state.power().ac_connected then bread.exec("brightnessctl set 40%") bread.notify("Battery " .. event.data.battery_percent .. "%, dimming") end end) end return M
Change the wallpaper and the whole desktop recolours.
Background, surface, and text are a fixed dark base that never moves. Only the
accent tracks the wallpaper: breadpaper derives a pywal palette,
bread-theme renders one shared stylesheet, and every bread app
live-reloads it. No rebuilds, and text stays legible because the ink colour is
picked by contrast.
Set the wallpaper, run pywal on it.
Render the shared GTK stylesheet from the new palette.
Watch the file, reload in place, instantly.
If an update breaks something, reboot and pick a snapshot.
Recovery is a GRUB menu, not a command you have to remember under stress.
Every pacman transaction is already snapshotted, and /usr/local
rides the root snapshot with it.
Reboot, open the snapshots submenu, boot a pre-transaction snapshot. Settings lists each one's number, date, and description.
Settings → Backup runs restic over $HOME to a local path or SFTP. Snapper covers root only, so home is backed up separately.
Boot the ISO, run bos-rescue: it finds the installed root and ESP, shows what it will touch, and asks before reinstalling GRUB.
The installer always writes EFI/BOOT/BOOTX64.EFI, so a lost NVRAM entry is one firmware-menu pick away from booting.
Compressed swap in RAM, and a deny-incoming firewall with mDNS allowed, both on from first boot.
fwupd is wired in and surfaced in Settings → Firmware.
bos-settings covers the day-to-day, GNOME-Settings style.
A Tauri 2 and Svelte control panel with live system state and control. Panels backed by a daemon also show its systemd status with start, stop, restart, and logs. Bread configs are edited non-destructively, so your comments and hand-tuned keys survive.
Everything has a binding. Press Super + / for the rest.
Binds live as JSON, so breadhelp's cheatsheet and the Settings
editors read the exact same source. Super is the Windows or Cmd key.
| Super + Return | Terminal (kitty) |
| Super + Space | App launcher (breadbox) |
| Super + E / B | Files (nautilus) / browser (Zen) |
| Super + U / M | Notes (breadpad) / notes manager (breadman) |
| Super + , / / | BOS Settings / keybind cheatsheet |
| Super + L / N | Lock / log out |
| Super + V | Clipboard history (breadclip) |
| Super + Shift + S / C / P | Screenshot region to file / to clipboard / whole screen |
| Super + F / I / P | Fullscreen / toggle floating / pseudotile |
| Super + 1..0 | Switch workspace (add Shift to move the window) |
| Super + arrows | Move focus. Super+Shift+hjkl moves the window; Super+Shift+arrows resizes it |
| Media & brightness keys | Work everywhere, including the lock screen |
The rough edges, up front.
A distro that hides its constraints wastes your afternoon. Here are the ones worth knowing before you install.
The ISO carries Mesa only, so AMD and Intel just work. There is no NVIDIA driver or firmware on the image; bos-nvidia-setup (or a Settings button) installs the proprietary driver afterward, but that path is opt-in.
X11-only apps run through XWayland. Most are fine; a few misbehave.
Enrolled via sbctl when the firmware is in Setup Mode. BOS cannot ship a Microsoft-signed shim.
GRUB cannot unlock LUKS2 with Argon2id, so full-disk encryption uses LUKS1.
Forgejo's Arch registry has no pacman-compatible db signatures yet, so that one repo is TLS-only until a signed mirror exists.
Hyprland is laggy under software rendering. Use virtio-vga-gl with -display gtk,gl=on.
Download a release, or build the image yourself.
Download
Every tagged release ships an ISO with a SHA256SUMS file and a detached signature from a dedicated release key. Verify before you flash:
gpg --import KEYS.asc gpg --verify SHA256SUMS.asc SHA256SUMS sha256sum -c SHA256SUMS
Build from source
On a native Arch machine, the image builds without a container. FAST_BUILD=1 swaps xz for zstd for quick iteration.
git clone https://git.breadway.dev/Breadway/bos cd bos sudo ./build-local.sh
The ISO lands in out/bos-<date>-x86_64.iso.
Try it in a VM
Boot the ISO under QEMU/KVM with virgl for a smooth Hyprland session:
qemu-system-x86_64 -enable-kvm \ -cpu host -m 8G -smp 8 \ -device virtio-vga-gl \ -display gtk,gl=on \ -cdrom bos-*.iso