Bread Ecosystem

A collection of Rust tools for the Linux desktop (Hyprland / Wayland / Arch). Install any product with a single command — no Rust toolchain required.

curl https://breadway.dev/get | sh
bakery install breadbar

Products

Package	Description
bread	Reactive automation daemon (breadd) + CLI — Lua scripting over Hyprland, udev, power, network, and Bluetooth events
breadbar	GTK4 status bar (workspaces, clock, CPU/RAM/battery/WiFi/Bluetooth) and D-Bus notification daemon for Hyprland
breadbox	GTK4 fuzzy app launcher for Hyprland with context-aware sorting; ships an icon-sync daemon (breadbox-sync)
breadcrumbs	Profile-aware Wi-Fi state machine with Tailscale exit-node management and a self-healing watch daemon
breadpad	Quick-capture scratchpad popup with AI-powered note classification, reminders, recurrence, and a full note viewer (breadman)
breadpaper	Wallpaper manager for the bread desktop

Recommended keybinds

The ecosystem assumes a Hyprland setup with SUPER as the modifier. The conventional bindings (used by BOS and recommended for any install):

Keys	Action
SUPER+Space	breadbox — app launcher
SUPER+U	breadpad — quick-capture notes/reminders
SUPER+M	breadman — note viewer / manager
SUPER+,	settings (bos-settings, where installed)

breadbar and breadd are services started at login (exec-once), not bound to keys.

Theming

All GUI products (breadbar, breadbox, breadpad) share one stylesheet via bread-theme. Background, surface, overlay, and foreground are always BOS's fixed dark values; only the accent colors are read from the pywal palette in ~/.cache/wal/colors.json. When that file is absent, the accents fall back to BOS's curated bread-toned defaults (not Catppuccin Mocha). The stylesheet is written to $XDG_RUNTIME_DIR/bread/theme.css; running apps watch that file and recolour live when it changes. Per-app CSS overrides live at ~/.config/<app>/style.css.

wal -i ~/Pictures/wall.png   # regenerate pywal palette
bread-theme generate         # render the shared stylesheet (run from a wal hook)

bread-theme subcommands:

Subcommand	Description
generate	Render the current palette and write the shared stylesheet (default)
reload	Same as generate; use after a palette change to trigger live recolour in running apps
path	Print the stylesheet path
print	Render the stylesheet to stdout without writing

The shared theming logic lives in the bread-theme crate in this repo. See BREAD_DESIGN_SYSTEM.md for the design tokens (fonts, spacing, radii, colour roles) the stylesheet is built from.

Installing bakery

bakery is the package manager for the ecosystem. Install it with the bootstrap script:

curl https://breadway.dev/get | sh
# or
curl -sSfL https://get.breadway.dev | sh

The script downloads the prebuilt bakery binary to ~/.local/bin/bakery and prints a note if that directory isn't on your PATH yet.

Using bakery

bakery list                    # all available packages
bakery list --installed        # only installed packages
bakery info breadbar           # version, binaries, system deps, services
bakery doctor                  # check system deps for installed packages
bakery doctor breadbar         # check system deps for a specific package

bakery install <pkg>           # install a package
bakery update <pkg>            # update a package
bakery update --all            # update everything
bakery remove <pkg>            # remove a package (data files are never deleted)

bakery install runs doctor first and bails with a clear message if any system dependency is missing. Binaries land in ~/.local/bin (override with BAKERY_BIN_DIR).

System dependencies by product

bakery doctor checks these automatically before any install. Required deps block installation; optional deps generate a warning but never block.

Package	Required	Optional
bakery	(statically linked, none)	—
bread	systemd-libs openssl zlib	bluez hyprland
breadbar	gtk4 gtk4-layer-shell iw libpulse	hyprland
breadbox	gtk4 gtk4-layer-shell librsvg	hyprland
breadcrumbs	networkmanager	tailscale sudo xdg-utils
breadpad	gtk4 gtk4-layer-shell	rocm-hip-runtime ollama hyprland

Install all required deps with sudo pacman -S <packages>. Use pacman -Q <pkg> to check whether any are already present.

Workspace

This repo is a Cargo workspace:

bread-ecosystem/
├── bakery/          # package manager binary
├── bread-theme/     # shared pywal + fixed-dark-base theming crate
├── registry/        # bread-ecosystem.toml — product registry
└── scripts/
    ├── get.sh       # curl | sh bootstrap
    └── gen-index.sh # generates dl.breadway.dev/index.json from release artifacts

Release pipeline

Each product repo (Breadway/bread, Breadway/breadbar, …) has .forgejo/workflows/release-*.yml that triggers on v* tags. The workflow runs on a self-hosted runner on hestia, builds a stripped x86_64 binary, deposits it at dl.breadway.dev/<pkg>/<version>/, updates index.json, and mirrors the binary to GitHub Releases as a fallback.

bakery always tries dl.breadway.dev first and transparently falls back to the GitHub Release URL recorded in the manifest.

Beyond stable releases, most products also publish dev and beta tracks — continuous builds off the dev and beta branches, respectively. See CONTRIBUTING.md for the branch/release workflow and docs/release-channels.md for the full track policy. Switch tracks with bakery track set <stable|beta|dev>.

Release artifact contract

Each product's release.yml must upload the following files alongside the binary to dl.breadway.dev/<name>/<version>/:

File	Purpose
bakery.toml	Metadata (deps, services, config) read by gen-index.sh
<binary>-x86_64.sha256	Checksum verified by bakery install and get.sh
*.service	systemd unit files installed by bakery install
*.example.toml / config.example.toml	Example configs copied on first install

gen-index.sh fails loudly if bakery.toml is missing — this is by design to catch omissions in the release workflow before they silently produce empty metadata in production.

License

MIT