Curated Software Distribution#

Curated Software Distribution is Universal Blue's project-specific approach to providing pre-configured software bundles through ujust commands and Brewfiles for common use cases. Rather than requiring users to individually select packages from repositories, this system delivers workflow-oriented bundles—collections of pre-tested, compatible tools organized around specific tasks like development, AI/ML work, or cloud-native operations.

The distribution mechanism centers on ujust bbrew, an interactive command that presents users with Homebrew Brewfiles for different use cases. Each Brewfile is validated in CI/CD before distribution and executed via bbrew, a wrapper tool from Valkyrie00/homebrew-bbrew that supports both Homebrew packages and Flatpak applications in a unified format.

This approach embodies Universal Blue's design philosophy: eliminate problems rather than document workarounds. Instead of providing documentation on assembling compatible toolchains, Curated Software Distribution delivers pre-validated bundles that users install with a single command. The system operates as a distinct abstraction layer above Bluefin's three-tier package management architecture (immutable base system, Flatpak applications, Homebrew CLI tools), abstracting complexity while maintaining system immutability through user-space installations.

Design Philosophy#

Curated Software Distribution implements workflow-level package management. Traditional package managers (apt, dnf, pacman) operate at the individual package level—users select specific packages, manage dependencies, and verify compatibility manually. Universal Blue's approach operates one level higher: users select workflows ("I need AI tools" or "I need Kubernetes tools"), and the system delivers a pre-validated collection.

The approach is built on Homebrew's Brewfile format, which provides declarative, version-controlled software bundle definitions. Brewfiles leverage Homebrew's Flatpak support, allowing a single bundle file to specify both command-line tools (Homebrew formulas) and graphical applications (Flatpaks) without exposing users to underlying package manager differences.

All bundles are validated through automated CI/CD workflows that verify package availability before distribution. This ensures every published bundle is installable and current, eliminating the common failure mode of stale documentation recommending unavailable packages.

Available Bundles#

Universal Blue maintains 10 curated bundles in the projectbluefin/common repository, spanning development tools, cloud-native infrastructure, AI/ML workflows, and desktop applications:

Bundle Deep Dive#

CLI Bundle (full contents) provides enhanced terminal tools organized by function:

• Shell enhancements: atuin (searchable history), starship (customizable prompt), zoxide (smart directory navigation)
• File operations: eza (modern ls), fd (fast find), ripgrep (recursive grep), bat (cat with highlighting)
• Development: gh (GitHub CLI), chezmoi (dotfile management), direnv (directory environments), mise (runtime management)
• Utilities: tealdeer (tldr pages), trash-cli, dysk, uutils-coreutils, ugrep, yq

AI Tools Bundle (full contents) delivers comprehensive AI/ML workflow support:

• Chat interfaces: aichat, gemini-cli, kimi-cli, llm, mistral-vibe, qwen-code
• Code assistants: claude-code, codex, copilot-cli, opencode
• Autonomous agents: Goose (block-goose-cli), OpenCode Desktop
• LLM management: ramalama (container-based local LLMs), LM Studio, llmfit
• Specialized: whisper-cpp (transcription), linux-mcp-server (Model Context Protocol)
• Desktop apps: Jan AI (Flatpak), Antigravity

CNCF Bundle (full contents) is the most comprehensive offering with 89 CLI tools organized by CNCF maturity level:

• Graduated (31): argo, flux, harbor-cli, istio, linkerd, prometheus, coredns, envoy, cilium-cli
• Incubating (25): argocd, crossplane, kn (Knative), falco
• Sandbox (33): dapr-cli, buildpacks, telepresence
• Graphical tools: Headlamp, OpenLens, Podman Desktop (Flatpaks)

Full Desktop Bundle (full contents) provides 59 GNOME Circle and community Flatpak applications:

• Reading: Foliate (ebooks), Komikku (manga), Biblioteca (OPDS)
• Productivity: Rnote (handwritten notes), Apostrophe (Markdown editor)
• Media: G4Music, GNOME Podcasts, Decibels
• Gaming: Cartridges (launcher)
• Design: Drawing, Emblem, Damask
• Communication: Tuba (Mastodon), Dino (XMPP)

Usage#

Basic Installation#

The primary interface is ujust bbrew:

ujust bbrew
# Interactive menu presents available bundles
# Select bundle (e.g., "ai-tools", "ide", "k8s-tools")
# bbrew executes installation

The command checks if bbrew is installed and prompts for installation if missing, then uses gum choose to present an interactive menu of all Brewfiles found in /usr/share/ublue-os/homebrew/.

Specialized Commands#

Beyond the interactive menu, specific bundles have dedicated commands:

ujust bluefin-cli - Directly installs all CLI tools from cli.Brewfile

ujust install-jetbrains-toolbox - Installs JetBrains Toolbox IDE launcher via Homebrew cask

ujust install-opentabletdriver - Installs OpenTabletDriver with udev rules, kernel module blacklist configuration, and systemd service setup

Updates and Maintenance#

ujust update manages system updates using bootc upgrade and automatically updates all Flatpak applications, keeping curated bundles current without manual intervention.

Custom Extensions#

Users can extend the system by placing custom justfiles in /usr/share/ublue-os/just/60-custom.just, allowing local customization without modifying base system files.

Technical Implementation#

Brewfile Format#

Brewfiles use Homebrew's declarative bundle format with four entry types:

• tap - Custom Homebrew repository references
• brew - CLI tools and command-line applications (formulas)
• cask - GUI applications and binaries
• flatpak - Graphical applications installed via Flatpak

Example from cli.Brewfile:

tap "valkyrie00/bbrew"
brew "atuin"
brew "bat"
brew "bash-preexec"
brew "valkyrie00/bbrew/bbrew"

Repository Structure#

All curated bundles are maintained in the projectbluefin/common repository:

• Shared bundles: system_files/shared/usr/share/ublue-os/homebrew/ (ai-tools, cli, cncf, experimental-ide, fonts, ide, k8s-tools, swift, artwork)
• Bluefin-specific bundles: system_files/bluefin/usr/share/ublue-os/homebrew/ (full-desktop, system-dx-flatpaks, system-flatpaks)
• ujust command definitions: system_files/shared/usr/share/ublue-os/just/apps.just

Custom Homebrew Taps#

Universal Blue maintains custom taps for packages not available in homebrew-core:

• ublue-os/tap - Main tap (VS Code, JetBrains Toolbox, Antigravity)
• ublue-os/experimental-tap - Experimental packages (complete JetBrains IDE suite, Cursor, OpenCode Desktop)
• valkyrie00/bbrew - bbrew tool itself
• anomalyco/tap - OpenCode CLI
• charmbracelet/tap - Charm CLI tools
• Additional CNCF-specific taps for cloud-native tooling

CI/CD Validation#

Automated validation runs in .github/workflows/validate-brewfiles.yaml on every pull request modifying Brewfiles:

1. Setup Homebrew using official GitHub Action
2. Find all Brewfiles in the repository
3. Extract and sync tap declarations
4. Extract formulas and casks with regex
5. Validate each package in parallel using xargs -P 8 with brew info (verification without installation)
6. Exit with failure if any package is invalid, blocking the PR

This custom parallel validation approach is faster than traditional brew bundle check and doesn't require actual package installation, making it efficient for CI environments.

System Immutability#

Curated bundles respect Bluefin's immutable architecture. Package layering is locked by default via LockLayering=true in /etc/rpm-ostreed.conf, preventing modifications to the base system layer. All curated bundle installations occur in user space:

• GUI applications install as Flatpaks (no system mutation)
• CLI tools install via Homebrew (user-space package manager)
• No system-level rpm-ostree package layering required
• rpm-ostree reset restores pure image mode if needed

bbrew Integration#

bbrew (from Valkyrie00/homebrew-bbrew) extends Homebrew's bundle functionality to support Flatpak entries alongside traditional formulas and casks. This integration eliminates the distinction between package types from the user perspective—Brewfiles can declaratively specify CLI tools, GUI applications, and Flatpaks in a single file, all managed through the same command interface.

Comparison with Traditional Package Management#

Traditional Linux package managers (apt, dnf, pacman, zypper) operate at the package level:

• Users select individual packages
• System-level installation modifies root filesystem
• Manual dependency resolution and compatibility verification
• Package-centric organization (search, install, remove single packages)

Curated Software Distribution operates at the workflow level:

• Users select use cases (development, AI/ML, cloud-native)
• Bundles contain pre-tested, compatible package collections
• CI/CD validation ensures installability before distribution
• User-space installation preserves immutable base system
• Versioned, reproducible bundles across machines

This layering sits atop Bluefin's three-tier package management architecture:

• System tier: Immutable base, updated as complete images
• GUI application tier: Flatpak, automatic daily updates
• CLI tool tier: Homebrew, independent management
• Curated bundle tier: Workflow-oriented collections spanning the lower tiers

Relevant Code Files#

Related Topics#

• ujust command system - Just-based command runner for system administration tasks
• Homebrew on Bluefin - Package manager for CLI tools and some GUI applications
• Flatpak integration - Universal Linux application distribution system
• Three-layer package management - Bluefin's immutable base + Flatpak + Homebrew architecture
• System immutability - rpm-ostree-based immutable filesystem design
• bootc upgrade process - Image-based system update mechanism
• bbrew tool - Wrapper enabling Homebrew bundles to install Flatpak applications