toolbox-create

Create a toolbox container for a specific distribution

$ toolbox create [[-d|--distro]] [distribution]

$ toolbox create [[-r|--release]] [release]

$ toolbox create [[-i|--image]] [name]

$ toolbox create [[-i|--image]] [registry.fedoraproject.org/fedora-toolbox:39]

$ toolbox create [[-d|--distro]] [fedora] [[-r|--release]] [f39]

toolbox create [options]

toolbox create [--container NAME] [--distro NAME] [--image IMAGE] [--release RELEASE] [--enforce-release] [--description DESCRIPTION]

--container NAME
    Specifies a custom name for the new toolbox container. If not provided, a default name will be generated.

--distro NAME
    Specifies the host distribution name to use for picking the default image. Useful when the host's distribution cannot be reliably detected.

--image IMAGE
    Specifies the container image to use for creating the toolbox (e.g., fedora-toolbox:39, registry.fedoraproject.org/fedora-toolbox:latest). This overrides --distro and --release.

--release RELEASE
    Specifies the release of the distribution to use for the image. For example, '39' for Fedora 39.

--enforce-release
    Causes toolbox-create to fail if a specific host release cannot be mapped to an image, instead of falling back to a default.

--description DESCRIPTION
    Provides a short, human-readable description for the toolbox, which can be viewed with toolbox list.

The toolbox-create command is a subcommand of the toolbox utility, designed to set up isolated Linux container environments for development and debugging.

These "toolboxes" provide a consistent and clean workspace where developers can install libraries, tools, and dependencies without affecting the host operating system. It leverages container runtimes like Podman or Docker to create unprivileged containers that seamlessly integrate with the host's user home directory, network interfaces, and devices. This allows for a smooth development workflow while maintaining a high degree of isolation for project-specific requirements.

When creating a toolbox, users can specify the desired container image, the distribution, and even a specific release. If not specified, toolbox-create intelligently attempts to match the host system's distribution and release to ensure compatibility and a familiar environment.

Toolboxes rely on an OCI container engine (like Podman or Docker) being installed and running on the host system. Without it, toolbox-create will fail.

As unprivileged containers, toolboxes have certain limitations; for instance, they cannot directly run system services or perform operations requiring root privileges on the host without specific workarounds.

While toolboxes integrate seamlessly with the host's home directory, care must be taken with file permissions, especially when interacting with files created by different user IDs inside and outside the container.

When --image is not specified, toolbox-create attempts to automatically select a suitable container image. It prioritizes matching the host system's distribution and release version (e.g., Fedora 39, RHEL 9) to provide a familiar and compatible environment. If a direct match isn't found, it might fall back to a generic or latest available image for the detected distribution.

A key feature of toolboxes created with toolbox-create is their deep integration with the host system. The user's home directory (/home/$USER) is automatically mounted into the container, allowing seamless access to personal files and projects. Furthermore, critical devices and network interfaces are shared, making the toolbox feel like a natural extension of the host, rather than a completely isolated virtual machine.

The toolbox utility, including toolbox-create, originated from the fedora-toolbox project, which was initially specific to Fedora Linux. Its primary aim was to provide a robust, isolated environment for developers to install various development tools and libraries without cluttering the host operating system.

Over time, the project evolved, becoming distribution-agnostic and being renamed simply to toolbox. This allowed it to be adopted and used more broadly across other Linux distributions like RHEL, CentOS Stream, and even community-driven efforts for Ubuntu. The command's development has consistently focused on simplifying containerized development workflows by leveraging the capabilities of OCI-compliant container runtimes such as Podman and Docker, making isolated environments easily accessible to end-users.

toolbox(1), toolbox enter(1), toolbox list(1), toolbox rm(1), podman(1), docker(1)