toolbx

About

Toolbx is a tool for Linux, which allows the use of interactive command line environments for development and troubleshooting the host operating system, without having to install software on the host. It is built on top of Podman and other standard container technologies from OCI.

Toolbx environments have seamless access to the user’s home directory, the Wayland and X11 sockets, networking (including Avahi), removable devices (like USB sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev database, etc..

This is particularly useful on OSTree based operating systems like Fedora CoreOS and Silverblue. The intention of these systems is to discourage installation of software on the host, and instead install software as (or in) containers — they mostly don’t even have package managers like DNF or YUM. This makes it difficult to set up a development environment or troubleshoot the operating system in the usual way.

Toolbx solves this problem by providing a fully mutable container within which one can install their favourite development and troubleshooting tools, editors and SDKs. For example, it’s possible to do yum install ansible without affecting the base operating system.

However, this tool doesn’t require using an OSTree based system. It works equally well on Fedora Workstation and Server, and that’s a useful way to incrementally adopt containerization.

The Toolbx environment is based on an OCI image. On Fedora this is the fedora-toolbox image. This image is used to create a Toolbx container that offers the interactive command line environment.

Note that Toolbx makes no promise about security beyond what’s already available in the usual command line environment on the host that everybody is familiar with.

Examples of use cases that fit this description can be found here.

Manual

Welcome to the world of this powerful command line utility. No longer will project environments clash with your host operating system, nor will you be limited to a single OS version.

Dive into this manual and unlock the potential to seamlessly switch between versions, isolate projects, and avoid software conflicts on your host system. Prepare to embark on a journey of efficient development and testing with Toolbx as your trusty companion.

Custom Images

Toolbx has built-in support for images corresponding to different operating system distributions. It’s also possible to create custom Toolbx images, and use them with the distro command line and configuration file options.

From a Containerfile

One way of creating a custom Toolbx image is to define its contents in a Containerfile and then use podman build --squash to build the image.

The easiest option is to base the custom image on one of the built-in images.

Here’s a Containerfile for a custom image that adds Emacs, GCC and GDB to the built-in fedora-toolbox:39 image available from registry.fedoraproject.org.

FROM registry.fedoraproject.org/fedora-toolbox:39

ARG NAME=my-fedora-toolbox
ARG VERSION=39
LABEL com.github.containers.toolbox="true" \
      name="$NAME" \
      version="$VERSION" \
      usage="This image is meant to be used with the toolbox(1) command" \
      summary="Image for creating Fedora Toolbx containers"

RUN dnf --assumeyes install emacs gdb gcc
RUN dnf clean all

It’s also possible to start from any OCI image, as long as the com.github.containers.toolbox="true" label is mentioned in the Containerfile.

The Containerfile can then be built to create a my-fedora-toolbox:39 image:

[user@hostname ~]$ podman build \
                     --squash \
                     --tag localhost/my-fedora-toolbox:39 \
                     /path/to/Containerfile/dir

From a Container

Another possibility is to create a custom Toolbx image from an existing Toolbx container by using podman commit --squash.

Here’s how to create a custom image similar to the one above, but based on a Toolbx container created from the built-in ubuntu-toolbox:22.04 image available from quay.io/toolbx.

Create the Toolbx container:

[user@hostname ~]$ toolbox create --distro ubuntu --release 22.04
Created container: ubuntu-toolbox-22.04
Enter with: toolbox enter ubuntu-toolbox-22.04

Alter it by installing Emacs, GCC and GDB:

[user@hostname ~]$ toolbox enter ubuntu-toolbox-22.04
⬢[user@toolbox ~]$ sudo apt update
Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
Get:2 http://security.ubuntu.com/ubuntu jammy-security InRelease [110 kB]
Get:3 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages [1208 kB]
…
…
…
⬢[user@toolbox ~]$ sudo apt --yes install emacs gcc gdb
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
…
…
…
⬢[user@toolbox ~]$ exit

A my-ubuntu-toolbox:22.04 image can then be created from the altered container:

[user@hostname ~]$ podman commit \
                     ubuntu-toolbox-22.04 \
                     localhost/my-ubuntu-toolbox:22.04