In this guide, we will discuss what is Toolbox and how to create and manage containerized development environment using Toolbox on Fedora Linux.
In the recent years, Linux container virtualization has gained a lot of momentum. In fact, the new generation of virtualization is containerization.
Nowadays, the application developers mostly uses containers as their preferred development environment. There are many tools exists to create and manage Linux containers. Podman, Docker, Vagrant are some popular container management applications.
Today, we will discuss yet another utility called Toolbox which makes it easy to use a containerized environment for everyday software development.
What is Toolbox?
Toolbox is an in-house tool from Fedora to create containerized command line environment on top of your Fedora base system.
It is particularly useful for setting up a use and throw software development environment where development tools and libraries can be installed and used.
Toolbox is specifically developed for OSTree based systems such as Fedora Core OS and Fedora Silverblue. As you may already know, the OSTree based systems are immutable.
Toolbox is built on top of OCI container images and Podman. It doesn't require any
root privileges to deploy containers. Good thing is Toolbox installation and usage is very easy to use and easy to remember!
The actual goal of immutable OS is to discourage the installation of software on the host system and encourage the users to install the software in containers.
Unlike the OSTree based systems, the containers are fully mutable. So you can install your favourite development and debugging tools, editors and SDKs inside the containers. Nothing gets installed on the host system.
To put this in layman terms, we can deploy a mutable container on an immutable host operating systems with the help of Toolbox.
How Toolbox Works?
By default, Toolbox creates the containers based on your current system. For instance, if your base system is Fedora 35, then toolbox will create a container based on Fedora 35. In this container, you can use package managers like
dnf to install your preferred applications. You can also create containers based on other Fedora versions as well.
You can start more than one container at a time and start working different projects simultaneously. Once you're done with the container, simply delete it and create a new one whenever you want. Again, the host system doesn't get affected in any way. This way we can maintain a clean host OS. This will also drastically avoid the clutter and reduce the process of host OS re-installation.
Install Toolbox on Fedora
Toolbox comes pre-installed with Fedora Silverblue 30 and newer editions. On Fedora workstation, you can install it using
yum package managers:
$ sudo dnf install toolbox
$ sudo yum install toolbox
Getting Started with Toolbox on Fedora Silverblue
Toolbox provides a small number of commands to create, list, enter and remove containers.
1. Display toolbox help
If you are new to Toolbox, it is better to display Toolbox help section to get a glimpse of what each command does. To view Toolbox help, use any one of the following commands:
$ toolbox --help
$ toolbox help
$ toolbox -h
Now let us start with creating new containers.
2. Create a new container
To create new container based on your current Fedora OS version, simply run:
$ toolbox create
This command will search for the base image to use to build the container from your local system. If there is no local image found, you will be prompted to download the respective image. Type y and ENTER key to download the image.
Image required to create toolbox container. Download registry.fedoraproject.org/fedora-toolbox:33 (500MB)? [y/N]: y Created container: fedora-toolbox-33 Enter with: toolbox enter
Toolbox will download an image matching the version of your current host system's OS from the Fedora registry and create a new container based on the downloaded image. The images are usually stripped-down version of actual distributions.
2.1. Create containers with custom name
The toolbox will automatically assign an unique name (e.g.,
fedora-toolbox-33) to the newly created container.
If you want to create a container with a custom name of your choice, use the
-c flag followed by the name of the container like below:
$ toolbox create --container mytoolbox-f33
$ toolbox create -c mytoolbox-f33
mytoolbox-f33 is the container's name.
3. Create a new container based on specific OS version
As I already mentioned, Toolbox creates containers based on the current OS version. For example, if you are running Fedora 34, Toolbox will create a container based on Fedora 34 image.
You can, however, create containers based on other versions as well. I created a Fedora 32 container on my Fedora 33 silverblue edition using the following command:
$ toolbox create --release f32
$ toolbox create -r f32
4. List containers
To list all locally available containers on your system, run:
$ toolbox list
IMAGE ID IMAGE NAME CREATED 9659c2039e64 registry.fedoraproject.org/f32/fedora-toolbox:32 4 months ago 675192cc4238 registry.fedoraproject.org/fedora-toolbox:33 4 weeks ago CONTAINER ID CONTAINER NAME CREATED STATUS IMAGE NAME 2cfb48d6a6c5 fedora-toolbox-32 4 months ago exited registry.fedoraproject.org/f32/fedora-toolbox:32 1f709997b871 fedora-toolbox-33 27 minutes ago configured registry.fedoraproject.org/fedora-toolbox:33
As you can see in the above output, I have two containers namely
fedora-toolbox-33 on my system.
The top section of output shows the details of the base images used to created the containers, such as Image ID, name of the image and when those images were created. In the bottom side, you will see the details of the containers such as Container ID, container name, when the container was created, and the status of the container.
You can also display either container details or image details separately. To list only the container details, use
$ toolbox list --containers CONTAINER ID CONTAINER NAME CREATED STATUS IMAGE NAME 2cfb48d6a6c5 fedora-toolbox-32 4 months ago running registry.fedoraproject.org/f32/fedora-toolbox:32 1f709997b871 fedora-toolbox-33 21 hours ago running registry.fedoraproject.org/fedora-toolbox:33
To list only the images, use
$ toolbox list --images IMAGE ID IMAGE NAME CREATED 9659c2039e64 registry.fedoraproject.org/f32/fedora-toolbox:32 4 months ago 675192cc4238 registry.fedoraproject.org/fedora-toolbox:33 4 weeks ago
Please note that the containers name and images names will look like almost same except the last part in their name.
The container name usually has hyphen (-) before the last part of its name (e.g.,
fedora-toolbox-33) and image name has colon (:) (e.g.,
5. Enter into the containers
We already have created the containers but haven't entered into them. So let us enter into a container using command:
$ toolbox enter
Once you entered the container, the shell prompt is prepended with a diamond symbol as shown in the following output:
Did you notice the diamond symbol on the far left side of the prompt? It means you are inside the container.
Containers seamlessly integrates with your current OS. Inside each container, you will find your existing username and permissions.
You can access to your home directory and several other locations as the way you do from your host system. You can also access to both system and session D-Bus, system journal and Kerberos etc.
Each container contains common command lines tools, including a package manager (e.g.,
DNF on Fedora). So, you can install and test any software inside the container.
For instance, the following command installs all necessary development tools:
$ sudo yum groupinstall "Development Tools"
5.1. Enter into a specific container
When you run the
toolbox enter command without any options, it opens the default toolbox container. The default container is the one that is based on your hosts OS.
If you want to open a different container, explicitly mention its name like below:
$ toolbox enter -c fedora-toolbox-32
-c is used to refer the container name and
fedora-toolbox-32 is the container name.
6. Exit toolbox
Once you're done with container, simply type
exit to log out from the container.
7. Run commands in containers without entering into them
A notable feature of Toolbox is you can run commands on a container without entering into them. The following command displays distribution release of the default container from the host system:
$ toolbox run cat /etc/redhat-release Fedora release 33 (Thirty Three)
When you run the
toolbox run command without any options, it will execute the commands on the default container. You can also run commands on other containers by specifying its name with
$ toolbox run -c fedora-toolbox-32 cat /etc/redhat-release Fedora release 32 (Thirty Two)
8. Stop running containers
After you exit from the container, it will keep running until you stop it. There is no direct toolbox command to stop a running container. However, we can use
podman command to stop the toolbox containers:
$ podman container stop fedora-toolbox-33
Remember Toolbox uses podman under the hood.
9. Remove toolbox containers and images
If you don't want a container or its base image, you can simply get rid of them like below.
Before deleting a container, make sure you exited from that container.
To remove a container, run:
$ toolbox rm fedora-toolbox-32
The above command removes the container named
To forcibly remove a container even if it is running, use
$ toolbox rm -f fedora-toolbox-32
To remove all containers, use
$ toolbox rm --all
Verify if the container is deleted by listing the available containers:
$ toolbox list
Similarly, you can remove the toolbox images using
toolbox rmi command like below:
$ toolbox rmi fedora-toolbox:32
Please note the
i in the above command. The
rm command removes the containers whereas
rmi command removes the images. Also don't forget to mention the correct name of the image to remove.
To remove all images, use
$ toolbox rmi --all
Use podman to manage toolbox containers and images
Since Toolbox is just the wrapper for Podman, you can directly use podman commands to manage containers.
To list toolbox containers using podman command, run:
$ podman ps -a
To list toolbox images with podman, run:
$ podman images
To start a container:
$ podman start fedora-toolbox-33
To view the live resource usage statistics of all running containers:
$ podman stats
To stop a container:
$ podman stop fedora-toolbox-33
$ podman inspect fedora-toolbox-33
$ podman rm <container-name>
$ podman rmi <image-name>
There are many podman commands available. You can view all available general commands and options from the podman help section:
$ podman --help
Containers are not just for experimental and learning purposes, they are also ideal for isolated development environment where you can work on different projects on different OS versions. Toolbox makes the management of containers a lot easier and better!