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 install tools for debugging in the usual way.
Toolbox solves this problem by providing a fully mutable container within
which one can install their favourite development and debugging 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 toolbox environment is based on an OCI
image. On Fedora this is the
fedora-toolbox image. This image is used to
create a toolbox container that seamlessly integrates with the rest of the
operating system by providing 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
Toolbox is installed by default on Fedora Silverblue. On other operating
systems it's just a matter of installing the
[user@hostname ~]$ toolbox create Created container: fedora-toolbox-33 Enter with: toolbox enter [user@hostname ~]$
This will create a container called
[user@hostname ~]$ toolbox enter ⬢[user@toolbox ~]$
[user@hostname ~]$ toolbox rm fedora-toolbox-33 [user@hostname ~]$
Toolbox requires at least Podman 1.4.0 to work, and uses the Meson build system.
The following dependencies are required to build it: - meson - go-md2man - systemd - go - ninja
The following dependencies enable various optional features: - bash-completion
It can be built and installed as any other typical Meson-based project:
[user@hostname toolbox]$ meson -Dprofile_dir=/etc/profile.d builddir [user@hostname toolbox]$ ninja -C builddir [user@hostname toolbox]$ sudo ninja -C builddir install
Toolbox is written in Go. Consult the src/go.mod file for a full list of all the Go dependencies.
By default, Toolbox uses Go modules and all the required Go packages are automatically downloaded as part of the build. There's no need to worry about the Go dependencies, unless the build environment doesn't have network access or any such peculiarities.
By default, Toolbox creates the container using an
OCI image called
<VERSION-ID> are taken from the
/usr/lib/os-release. For example, the default image on a Fedora 33
host would be
This default can be overridden by the
--image option in
but operating system distributors should provide an adequately configured
default image to ensure a smooth user experience.
Toolbox customizes newly created containers in a certain way. This requires certain tools and paths to be present and have certain characteristics inside the OCI image.
mkdir(1): for hosts where
/home is a symbolic link to
rmdir(1): for hosts where
/home is a symbolic link to
/etc/host.conf: optional, if present not a bind mount
/etc/hosts: optional, if present not a bind mount
/etc/krb5.conf.d: directory, not a bind mount
/etc/localtime: optional, if present not a bind mount
/etc/machine-id: optional, not a bind mount
/etc/resolv.conf: optional, if present not a bind mount
/etc/timezone: optional, if present not a bind mount
sudo(8) access inside containers. The following is necessary
for that to work:
The image should have
sudo(8) enabled for users belonging to either the
wheel groups, and the group itself should exist. File an
issue if you really need
support for a different group. However, it's preferable to keep this list as
short as possible.
The image should allow empty passwords for
sudo(8). This can be achieved
by either adding the
nullok option to the
PAM(8) configuration, or by
NOPASSWD tag to the
Since Toolbox only works with OCI images that fulfill certain requirements,
it will refuse images that aren't tagged with
com.github.debarshiray.toolbox="true" labels. These labels are meant to be
used by the maintainer of the image to indicate that they have read this
document and tested that the image works with Toolbox. You can use the
following snippet in a Dockerfile for this:
LABEL com.github.containers.toolbox="true" \ com.github.debarshiray.toolbox="true"