Toolbox

As an immutable host, Silverblue is an excellent platform for container-based development and, for working with containers, buildah and podman are recommended.

Silverblue also comes with the toolbox utility, which uses containers to provide an environment where development tools and libraries can be installed and used.

Toolbox makes it easy to use a containerized environment for everyday software development and debugging. On immutable operating systems, like Fedora Silverblue, it provides a familiar package-based environment in which tools and libraries can be installed and used. However, toolbox can also be used on package-based systems.

Why use toolbox?

Using toolbox containers to install development tools offers a number of advantages:

  • It keeps the host OS clean and stable, and helps to avoid the clutter that can happen after installing lots of development tools and packages.

  • Containers are a safe space to experiment: if things go wrong, it’s easy to throw a toolbox away and start again.

  • Containers are a good way to isolate and organise the dependencies needed for different projects.

How it works

Toolbox takes the work out of using containers, by providing a small number of simple commands to create, enter, list and remove containers. It also integrates toolbox containers into your regular working environment, to make it easy for you to use them as an everyday development space.

Each toolbox container is an environment that you can enter from the command line. Inside each one, you will find:

  • Your existing username and permissions

  • Access to your home directory

  • Common command lines tools, including the DNF package manager

In other words, toolbox containers look, feel and behave like a standard Linux command line environment.

In most cases, when a command is run inside a container, the program from inside the container is used. However, there are a few special cases where the program on the host is used instead. One example of this is the toolbox command itself; this makes it possible to use toolbox from inside toolbox containers.

Installation

Fedora Silverblue

Toolbox is preinstalled on Fedora Silverblue 30 or newer. On older versions, it can be installed with the following command:

$ rpm-ostree install toolbox

This will install toolbox as a layered RPM.

Fedora Workstation

Toolbox can be installed on Fedora Workstation (or any package-based version of Fedora) with the following command:

$ sudo dnf install toolbox

Your first toolbox

Once toolbox is installed, two simple commands are required to get started:

$ toolbox create

This will download an OCI image and create a toolbox container from it. Once this is complete, run:

$ toolbox enter

Once inside the toolbox, you can access common command line tools, and install new ones using DNF.

When the prompt is inside a toolbox, it is prepended with a diamond: this indicates that the prompt is inside a toolbox container.

Commands and usage

toolbox create [--container <name>]

Creates a toolbox container. This will download an OCI image if one isn’t available (this is required to create the container). By default a Fedora image matching the version of the host is used. Used without options, toolbox create will automatically name the container it creates. To create additional toolboxes, use the --container <name> option.

toolbox enter [--container <name>]

Enters a toolbox for interactive use. Used without options, toolbox enter opens the default toolbox. If there is more than one toolbox, use the --container name option to specify the toolbox to enter.

toolbox list

Lists local toolbox images and containers. Note: it is typical to see two images listed, one with a localhost prefix and one with a registry.fedoraproject.org prefix. These are a normal result of the toolbox creation process.

toolbox rm [--force] <name>

Removes one or more toolbox containers. The --force option removes the container even if it is running.

toolbox rmi [--force] <name>

Removes one or more toolbox images.

toolbox --help

Lists available commands.

Exiting a toolbox

To return to the host environment, either run exit or quit the current shell (typically Ctrl+D).

Under the hood

Toolbox uses the following technologies:

Contact and issues

To report issues, make suggestions, or contribute fixes, see toolbox’s GitHub project.

To get in touch with toolbox users and developers, use Fedora’s Discourse instance, or join the #silverblue IRC channel on Freenode.