Day to Day Operation#

Bluefin is designed to be installed for the life of the hardware without reinstallation. Unlike traditional operating systems, the image is always pristine and "clean", making upgrades less problematic. Updates are automatic and silent by default.

This typically means you can set up your system once, and then have it remain that way. Then likely you'll never have to come back here. 🙂

Installing Applications#

Use Bazaar to install applications from Flathub. System updates and upgrades are not handled by this application, its scope has been reduced to only install Flatpaks from Flathub. Two flatpak management tools are included:

• Warehouse provides application management.
• Flatseal is also included for permission management.

System Updates#

Bluefin is designed to be "hands off". The system checks for updates every six(6) hours. This includes system updates, flatpaks, pet containers, and homebrew.

• Most images are published weekly, but we may push a new update at any given time.

Updates are applied when the system reboots. Therefore, it is recommended to routinely power off your device when it's not being used to ensure kernel updates are being applied. Application updates (like the browser) happen independently of this and don't require a reboot.

Machine firmware updates are provided through the Firmware application.

Managing Updates#

In Settings → Network → A network setting, set Metered Connection: has data limits or can incur charges to pause Bluefin updates:

Streams and Throttle Settings#

Bluefin offers images based on the current version of Fedora, as well as a CentOS based image. This is to provide users with flexibility as to how aggressive they want their updates. These are referred to as "streams".

Bluefin#

stable: This is the default stream for Bluefin, aimed at most users. It is always aliased to the current version of Fedora but follows the Fedora CoreOS release schedule. This means that kernel upgrades come about 2 weeks after they land in Fedora, which can be useful for avoiding kernel regressions since the Bluefin team can pin to a specific kernel in those circumstances. We call this "gating" the kernel. stable-daily is available for those who want daily builds.

You can choose from three rolling tags, or lock to a specific version of Fedora. Check the release notes for specific version information:

Note: Bluefin LTS and GDX not shown here, refer to their respective documentation for more details.

The major difference between latest and stable is the kernel cadence and when they do a major upgrade. latest will upgrade to the next major Fedora release as soon as it is available and builds daily. stable will upgrade when CoreOS does its userspace upgrade, which is usually a few weeks afterwards, and builds weekly or daily. Users can choose the stable-daily image for daily stable updates, or stick to stable for weekly builds.

Gated Kernel#

The stable tag features a gated kernel. This kernel follows the same version as the Fedora CoreOS stable stream, which is a slower cadence than default Fedora Silverblue. The Universal Blue team may temporarily pin to a specific kernel in order to avoid regressions that may affect users.

Adding and editing kernel boot arguments is handled by bootc kargs. Check the upstream documentation for more information.

Switching between Streams#

Use the ujust rebase-helper command to select rebase and select a specific stream:

Or select date and choose an older image.

Switching between streams manually#

Bluefin uses bootc to manage the operating system image. To inspect your current and staged deployments, run:

sudo bootc status

This displays your booted image, staged update (if any), and rollback target:

Current staged image: ghcr.io/projectbluefin/bluefin:stable
    Image version: 43.20260901.0
    Image digest: sha256:...
Current booted image: ghcr.io/projectbluefin/bluefin:stable
    Image version: 43.20260825.0
    Image digest: sha256:...

The ghcr.io/projectbluefin/bluefin:stable reference indicates the image and stream tag. Look for :stable, :latest, or pinned date tags.

If you have locally layered packages, reset them before switching streams:

rpm-ostree reset

Pro Tip: Bluefin's release notes contain stream switching instructions for each release.

Use the bootc switch command to move to a different stream:

Manual Switch Examples#

sudo bootc switch ghcr.io/projectbluefin/bluefin:stable --enforce-container-sigpolicy

sudo bootc switch ghcr.io/projectbluefin/bluefin:testing --enforce-container-sigpolicy

sudo bootc switch ghcr.io/projectbluefin/bluefin-nvidia:stable --enforce-container-sigpolicy

sudo bootc switch ghcr.io/projectbluefin/bluefin:stable-20260825 --enforce-container-sigpolicy

sudo bootc rollback

skopeo inspect docker://ghcr.io/projectbluefin/bluefin:stable

This will show all the available tags and useful metadata like image and kernel versions.

Check the bootc documentation for more information.

Virtual Private Networks (VPN)#

Tailscale is included by default to provide VPN services for both desktop and development use cases. Tailscale is pretty useful.

• Using Tailscale with Mullvad - provides the best out of the box experience
• Using Tailscale with Docker - for development
• Using the system tray with tailscale - follow this for setting up the tailscale icon in the system tray. Note that wl-clipboard is already included on the system so you do not need to install that.
• Tailscale's YouTube channel has lots of great tips and tricks
• Good VPN providers may provide Wireguard configurations that can be imported directly into the Network Manager, check their documentation for more information:
  • NordVPN

There are also VPN providers on Flathub which will offer a good experience:

• Mozilla VPN (Donate)
• ProtonVPN client - available on Flathub

Other VPN providers that are not explicitly mentioned here may a poor packaging experience and are not recommended. If your VPN provider falls into this category then exporting the wireguard configuration and importing it manually may be the best approach.

Local Layering#

Adding packages directly onto the host image is discouraged in Bluefin. The operating system is designed to remain pristine and reproducible as an OCI image managed by bootc.

Workloads should be isolated in containers (via Distrobox or Devcontainers), CLI tools installed via Homebrew, and graphical applications installed from Flathub.

If you must temporarily layer a host package:

rpm-ostree install <package>

To remove all layered packages and return to the pure image baseline:

rpm-ostree reset

Reboot to apply.

Overwriting System Defaults#

Bluefin system defaults are shipped on the base image along with Fedora configuration in /usr/etc. Most of these can be overridden by placing a file in /etc.

For example, the Distrobox configuration is in /usr/etc/distrobox/distrobox.ini. Your customization options will be placed in /etc/distrobox/distrobox.ini. This is useful for situations where you need a copy of the original file for reference.

Check the XDG Base Directory Specification for more information on configuration options, in particular ~/.local and ~/.config.

Community Aliases and Workarounds#

just is used as a task runner on Bluefin. These are commonly community convenience aliases, or more complex scripts that help automate some tasks or initial setup. This is aliased as ujust, so that you can use just itself for your other projects.

Getting Started with ujust#

• ujust --choose - Shows every command and the script that is being executed when that command is chosen. Useful for browsing the available commands
• ujust -n $command - The -n will run a command in dry-run mode, this is useful for inspecting the commands being run

Curated Tool Bundles#

Bluefin includes curated CLI tool collections. These commands install curated collections of tools via Homebrew:

System Commands#

Developer Experience Commands#

Application Installation Commands#

Note that generally speaking Bluefin tries to keep the system Justfiles finely scoped, most of these are workarounds and not full-fledged commands. They may get removed or changed depending on the problem they were initially meant to solve.

Managing Extensions#

Bluefin uses the Extension Manager by Matthew Jakeman to manage the desktop extensions. The application is included by default. You can access it via the Logo Menu (thanks Aryan Kaushik!)

This is useful if you decide you do not want to use some of the ones bundled with Bluefin.

Remote Management#

Bluefin and Aurora include Cockpit for machine management. We're hoping to include more out-of-the-box management templates, please check this issue if you're interested in volunteering.

Verification#

These images are signed with sigstore's cosign. You can verify the signature by downloading the cosign.pub key from this repo and running the following command:

cosign verify --key cosign.pub ghcr.io/projectbluefin/bluefin