The `bluefin-cli` Container

Introducing bluefin-cli

Note: This feature is under heavy development. If all of this is confusing to you ignore it. :smiley:

ujust bluefin-cli will install bluefin-cli, Bluefin’s opt-in command line experience. It is a dedicated toolbox container that is designed to give the user access to as much software as possible while providing a modern Linux command line experience. It is purposely decoupled from the host system so that it can run on any Linux system.

bluefin-cli comes preconfigured with the Homebrew package manager and comes ready to go out of the box. It is the current recommended method to install command line applications in Bluefin.

  • System level commands that are not in the container such as rpm-ostree, podman, docker, systemctl, and ujust transparently work. Commands that require sudo on the host will not work, use the host terminal in Ptyxis for those use cases.
  • The brew command works as it does on other operating systems.
  • This introductory video goes over the features and history of Wolfi, which is designed for running in containers.
  • We feel that a distroless approach to deliver the entirety of the Homebrew ecosystem in a container is the perfect compliment to an existing host operating system.

Included software

bluefin-cli comes with the latest versions of bash, fish, and zsh included, as well as some other fantastic command line tools:

The entire container is rebuilt every day from scratch, and Wolfi’s aggresive update policy ensures that Bluefin is always on the latest version of software. Fully automated.

Brew’s state is volume mounted to a file in your home directory so your container is fresh but your additional packages remain untouched. At this time it is strongly recommended to maintain a backup of your brew package list via the brew bundle subcommand.

The apk package manager is preferred for fully declarative setups with boxkit or locally. You can file package requests on the WolfiOS repository for packages that you may need.

The intended endstate of bluefin-cli is a fully automated declarative config managed via git using Wolfi packages for clean daily rebuilds. brew is used to fill out the “long tail” of existing software.

Use bluefin-cli on any Linux

bluefin-cli is for everyone! Here’s the distrobox command.

distrobox create -i -n bluefin

It’ll work with any terminal, but is probably enjoyed to it’s fullest with Ptyxis. If you’re not on a Bluefin host we recommend grabbing the quadlets to get a managed, auto-updating experience.

Why a new container instead of just using Ubuntu or Fedora?

Alpha and Beta versions of Bluefin included Ubuntu as the default terminal experience. However, the team desired a distrobox that was designed from the bottom up to be a terminal experience instead of a traditional distribution. This is the way.

WolfiOS was chosen due to:

  • These technical features
  • The team’s investment in tooling and automation
  • Aggressive update cadence
  • Packaging priorities strongly skew towards the tools our target audience wants.

Note: Ubuntu and Fedora containers will always be included and receive the same optimizations such as instant-launch, Ptyxis integration, etc.

Assembling custom containers (Optional)

For specific projects we recommend assembling on-demand distroboxes so that they are built fresh from scratch. Use the ujust assemble shortcut to declaratively build distroboxes defined in /etc/distrobox/distrobox.ini. This command will destroy your existing container and pull a new one from scratch.

Modify /etc/distrobox/distrobox.ini to add your custom packages to the stock containers so that your preferred environment can be rebuilt. Check out Declaring your own personal distroboxes for more information. Here’s an example distrobox.ini file


It is indeed very nice, just a few things that are confusing me, If i add something to zshrc file that let’s say references to fzf keybindings in my main terminal, then i go to bluefin, it gives errors related to missing files.

And if I install the fzf inside bluefin, now if i go back to let’s say Arch Distrobox, it obviously gives error. How should I handle such problems, since its not really a bug per say, but more on how to handle various distroboxes.

Hi Jorge,

thanks for the great work on bluefin!
I’ve just tried the bluefin-cli container and i noticed that i can not copy to the system clipboard in neovim. Is that something that we can make work in the cli container?

Best regards,

I may have asked before, but when I see this note

Note: We do not recommend installing Homebrew on the host as this can lead to conflicting libraries between brew and the system.

I wonder if it’s still the case. Or some mechanism has been implemented to resolve the conflict? Or the conflict only happens under certain scenarios, … ?

(Btw thanks for the good work!)

Oh good catch! Yeah the ujust brew command will safely install on the host. I’ve updated the page, thanks!

1 Like

I noticed the following error message when running ujust update, when topgrade attempts to update bluefin-cli container:

── 16:11:40 - Distrobox ────────────────────────────────────────────────────────
 Upgrading bluefin-cli...
distrobox: Installing basic packages...
BusyBox v1.36.1 (2024-03-27 13:51:06 UTC) multi-call binary.

Usage: su [-lmp] [-s SH] [-] [USER [FILE ARGS | -c 'CMD' [ARG0 ARGS]]]

Run shell under USER (by default, root)

        -,-l    Clear environment, go to home dir, run shell as login shell
        -p,-m   Do not set new $HOME, $SHELL, $USER, $LOGNAME
        -c CMD  Command to pass to 'sh -c'
        -s SH   Shell to use instead of user's default
distrobox: Setting up devpts mounts...
distrobox: Setting up read-only mounts...
distrobox: Setting up read-write mounts...
/usr/bin/entrypoint: line 1465: container_user_name: parameter not set
Error: An error occurred
su-exec: -S: No such file or directory

Looks like maybe busybox problem? Didn’t want to open a GitHub issue before checking with y’all here.

I also tried to add packages to the /etc/distrobox/distrobox.ini file under both wolfi and bluefin-cli, but they are not picked up from what I can tell.

Yeah we don’t want to upgrade that one in place that one gets built fresh in CI, please file an issue in ublue-os/toolboxes and we’ll take a look, thanks!

1 Like

I filed an issue about a week ago and forgot to update the thread here.

My use case is relatively simple: I want to be able to use 1Password CLI from inside the container with the help of distrobox-host-exec, which requires the libinput-dev package and I also add icu-dev.

The next use case for me is to be able to run full test suites for any project I am working on, including Playwright, and that requires a few packages in order to run properly inside of Wolfi.

  1. That said, how would I go about spinning my own build of bluefin-cli?

  2. Can I replace the default bluefin-cli image with an image of my choosing?

  3. Or, can I somehow replace the defaults in Ptyxis and have them persist over updates?

Playwright requires the following libraries:

  • cairo-dev
  • cups-dev
  • alsa-lib
  • pango-dev
  • libxdamage-dev
  • libxcomposite-dev
  • libdrm-dev
  • libnspr
  • libatk-1.0
  • libatk-bridge-2.0
  • libxrandr-dev
  • libxkbcommon-dev
  • libnss-dev
  • mesa-gbm

How can I help? I would like to find a solution and then update the documentation as well to cover this, if y’all think it is a generic enough concept to warrant a section in the docs.

1 Like

Boxkit is a set of actions designed to make your own toolboxes, snag that to set up your own repo via the “Use this template” function and you can start customizing:

Here’s mine as an example - which is just bluefin-cli with some extra added packages.

Any contributions in docs would be appreciated! The docs are set as a wiki (or just post them as a comment somewhere and we can start to integrated. They’re almost constantly WIP so if you need to leave boilerplate and TODOs then that’s not a problem. Thanks!

1 Like

I created tbjers/bluefin-cli! That was easy.

1 Like

When sourcing files, you should check if they exist first.

[[ -f /path/to/file ]] && source /path/to/file

Unsure if things like xclip/wl-copy are available. But we can check.

wl-clipboard doesn’t appear to be available in wolfi, I’ll see if we can get it in there.

Hey, @j0rge my bluefin-cli builds started failing today. Not sure what has changed and why it’s all of a sudden failing with a zstd-related error:

Error during manifest conversion: "application/vnd.oci.image.layer.v1.tar+zstd": zstd compression is not supported for docker images

Any ideas on how to solve this?

Aha! I just pushed these to use zstd, if you’re on the latest version of docker this should work, what version are you on?

I am using the following workflow (same as the boxkit template, I think): tbjers/bluefin-cli/blob/main/.github/workflows/build-boxkit.yml

I see that the workflow file for the toolboxes repo is using newer versions of a variety of actions. Do we want to update the boxkit template workflow?

Discourse won’t let me link the workflow file in my repo, lol

Oh I think I see the problem. I’ll need to revert zstd for the toolboxes until the ubuntu 24.04 runners are out of beta. I’ll revert and push now!

PR here: revert: "chore: push images with zstd:chunked" by castrojo · Pull Request #103 · ublue-os/toolboxes · GitHub

1 Like