Homebrew Tap Usage on Bluefin#

Bluefin now includes containerd in the base image (details), allowing you to install and run Docker directly from Homebrew. This removes the need for dedicated DX images for most developer workflows.

Installing Docker and Other Tools#

To install Docker and other developer tools, use Homebrew as follows:

brew install docker
brew install --cask ublue-os/tap/visual-studio-code-linux
brew install --cask ublue-os/tap/vscodium-linux
brew install --cask ublue-os/tap/jetbrains-toolbox-linux
brew install --cask ublue-os/tap/lm-studio-linux
brew install --cask ublue-os/tap/1password-gui-linux
brew install --cask ublue-os/tap/framework-tool
brew install --cask ublue-os/tap/bluefin-wallpapers
brew install --cask ublue-os/tap/bluefin-wallpapers-extra
brew install --cask ublue-os/tap/aurora-wallpapers
brew install --cask ublue-os/tap/bazzite-wallpapers
brew install --cask ublue-os/tap/framework-wallpapers
brew install ublue-os/tap/asusctl
brew install ublue-os/tap/ramalama
brew install nvim
brew install micro
brew install helix
brew install devcontainer

Note: With containerd now present, Docker installed via Homebrew will work out-of-the-box. For more on Docker usage, see Homebrew Docker documentation.

Experimental IDEs#

Install JetBrains IDEs and other editors from the experimental-ide.Brewfile:

brew bundle --file=system_files/shared/usr/share/ublue-os/homebrew/experimental-ide.Brewfile

CNCF & Cloud-Native Tools#

The cncf.Brewfile includes Flatpak entries for graphical tools (Headlamp, OpenLens, Podman Desktop). Use Flatpak for graphical apps, Homebrew for CLI tools.

Wallpaper Casks: Linux & macOS Support#

Wallpapers for GNOME include metadata. KDE users should follow these instructions for Plasma Dynamic wallpapers. For details on wallpaper cask structure and automation, see the homebrew-tap README and scripts/bump-wallpapers.py.

Included Software#

• Docker (now supported out-of-the-box via Homebrew)
• 1Password (password manager)
• ASUSCTL (ASUS ROG laptop tools)
• JetBrains Toolbox
• LM Studio (local LLM manager)
• Visual Studio Code, VSCodium
• Framework System Tool
• ramalama
• Wallpapers for Bluefin, Aurora, Bazzite, Framework
• Editors: nvim (Neovim), micro, helix
• Devcontainer CLI

Experimental IDEs:

• JetBrains IDEs (CLion, DataGrip, DataSpell, GoLand, IntelliJ IDEA, PhpStorm, PyCharm, Rider, RubyMine, RustRover, WebStorm)
• Cursor, Antigravity, Emacs App (Linux versions)

Cloud-Native & CNCF Tools:

• CLI tools for Kubernetes, CNCF, and cloud-native development (cncf.Brewfile)
• Flatpak support for graphical tools: Headlamp, OpenLens, Podman Desktop

For a full list of available casks and formulae, see the ublue-os/tap repository and common Brewfiles.

Experimental IDEs & Flatpak Support#

Experimental IDEs#

The experimental-ide.Brewfile provides access to a wide range of JetBrains IDEs and other editors for Linux:

To install all experimental IDEs:

brew bundle --file=system_files/shared/usr/share/ublue-os/homebrew/experimental-ide.Brewfile

See the experimental-ide.Brewfile for the full list and latest additions.

Flatpak Support for CNCF Tools#

The cncf.Brewfile includes Flatpak entries for graphical cloud-native tools:

Install these with Flatpak for a graphical experience. For CLI tools, continue using Homebrew as usual.

For more details, see the CNCF Brewfile reference.

Repository Structure#

• Casks/: Ruby cask definitions for GUI apps and wallpapers (example)
• Formula/: Ruby formulae for CLI tools (example)
• .github/scripts/: Automation scripts for version checks (example)
• scripts/: Project-level automation, including bump-wallpapers.py for updating wallpaper cask versions and SHA256s
• .github/workflows/: CI/CD workflows for bottle builds, tests, publishing, and automated package version bumps (bottle-asusctl.yml, tests.yml, publish.yml, bump.yml, bump-wallpapers.yml)

Automation & CI/CD#

Automated version checks and updates for formulae and casks use Python scripts and GitHub Actions. The tap includes workflows for both general package updates (bump.yml) and a dedicated wallpaper cask updater (bump-wallpapers.yml). The wallpaper workflow runs on a schedule and uses scripts/bump-wallpapers.py to automatically update all wallpaper casks (Bluefin, Bluefin Extra, Framework, Aurora) to the latest upstream release, updating all SHA256 checksums for macOS, KDE, GNOME, and PNG variants. This ensures that wallpaper casks are always current and multi-platform.

The main bump workflow creates PRs to bump package versions using brew bump. Both workflows avoid duplicate PRs. Homebrew test-bot runs on PRs and pushes (tests.yml). Bottles are built and published automatically; PRs are merged after CI passes. Renovate bot handles dependency bumps via renovate.json.

Contribution Guide#

Fork the repository on GitHub, clone your fork locally, create a branch for your changes, and write or update casks/formulae in the appropriate directory. Follow Homebrew’s Formula Cookbook and Cask Cookbook. Commit with Conventional Commits, push your branch, and open a PR against main. PRs trigger automated tests and bottle builds. Maintainers review and merge after CI passes.

For style, structure, and best practices, see:

• Homebrew’s official contribution docs
• How to Create and Maintain a Tap
• Acceptable Formulae and Acceptable Casks

Troubleshooting & Caveats#

Out of scope: browsers, apps that should be flatpaks, general requests for common apps. Most packages are for automation and background use; users typically interact via scripts or higher-level tools. For KDE wallpaper support, see bluefin-wallpapers-plasma.

Antigravity Authentication/Browser Integration Issues

If authentication fails or the browser doesn't open Antigravity after installation, run these commands to properly configure the URL scheme handler:

xdg-mime default antigravity-url-handler.desktop x-scheme-handler/antigravity
update-desktop-database ~/.local/share/applications

This ensures that antigravity:// URLs are properly associated with the application for authentication workflows and browser integration.

Docker Troubleshooting

For Docker troubleshooting, see Homebrew Docker FAQ and containerd documentation.

Upstream Documentation & References#

• Homebrew Documentation
• How to Create and Maintain a Tap
• Formula Cookbook
• Cask Cookbook
• Contribution Guide
• Acceptable Formulae
• Acceptable Casks
• Homebrew on Linux
• containerd Documentation
• Project Bluefin Contributing