Distro support

By default, Toolbx creates the container using an OCI image called <ID>-toolbox:<VERSION-ID>, where <ID> and <VERSION-ID> are taken from the host’s /usr/lib/os-release. For example, the default image on a Fedora 36 host would be fedora-toolbox:36.

This default can be overridden by the --image option in toolbox create, but operating system distributors should provide an adequately configured default image to ensure a smooth user experience.

Image requirements

Toolbx specifies the entry points of newly created containers in a certain way. It’s best if the OCI image doesn’t specify any entry point of its own to avoid interfering with the desired command line arguments. In other words, there shouldn’t be any Entrypoint in the podman inspect output for the image. A wrong set of arguments will prevent toolbox enter from working.

If the image has a parent base image that does specify an entry point, then it can be reset with this Containerfile snippet:


Toolbx 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.



Toolbx enables sudo(8) access inside containers. The following is necessary for that to work:

Since Toolbx only works with OCI images that fulfill certain requirements, it will refuse images that aren’t tagged with com.github.containers.toolbox="true" and 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 Toolbx. You can use the following snippet in a Dockerfile for this:

LABEL com.github.containers.toolbox="true"

The label com.github.debarshiray.toolbox="true" was used in previous versions of toolbx but is currently deprecated.