toolbox-run

Run a command inside a specific toolbox container

$ toolbox run [[-c|--container]] [container_name] [command]

$ toolbox run [[-d|--distro]] [distribution] [[-r|--release]] [release] [command]

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

toolbox-run [OPTIONS] [CONTAINER] [COMMAND...]

-c, --container NAME
    Specifies the name of the Toolbox container to execute the command within. If omitted, the default container (e.g., fedora-toolbox-38) is used.

-i, --image IMAGE
    Specifies the container image to base the Toolbox on. This option is primarily relevant if the specified container does not exist and toolbox-run attempts to create it implicitly.

-r, --release RELEASE
    Specifies the release of the container, such as 38 for Fedora 38. This helps identify or create the correct container if multiple releases are available.

--distro DISTRO
    Specifies the distribution of the container, for example fedora or rhel. This works in conjunction with --release.

-R, --root
    Executes the command inside the container with root privileges. By default, commands run as the current user.

--log-level LEVEL
    Sets the logging verbosity level for toolbox-run itself. Common levels include debug, info, warn, error.

--log-file FILE
    Directs logging output to the specified file path instead of standard error.

--version
    Displays the version information of the toolbox-run command and exits.

--help
    Shows a help message and exits.

toolbox-run is a powerful utility within the toolbox ecosystem, designed to execute a specified command directly inside an existing Toolbox container. Unlike toolbox enter, which provides an interactive shell session, toolbox-run is ideal for non-interactive tasks, scripting, and automation. It allows developers to leverage the isolated and customizable environment of their Toolbox containers for single-shot operations like compiling code, running tests, or performing system administration tasks without manually entering and exiting the container. By simply specifying the container name (or using the default) and the command, users can seamlessly run their tools and applications within a consistent and controlled environment, mirroring the experience of executing commands on a traditional Linux system while benefiting from container isolation. This capability significantly streamlines workflows for immutable operating systems and container-centric development.

toolbox-run relies on the toolbox environment being correctly set up and requires podman as its underlying container engine.
While toolbox-run can implicitly create a container if it doesn't exist (when --image or related options are used), it's generally recommended to explicitly create containers using toolbox create first for better control.
The command executes in an isolated environment; changes made inside the container, such as installing packages, persist within that container but do not affect the host system directly.
The standard input, output, and error streams of the command executed inside the container are connected to toolbox-run's streams, enabling seamless interaction or scripting.

When no CONTAINER name is specified, toolbox-run intelligently selects the default Toolbox container, typically the one corresponding to the host's operating system release (e.g., fedora-toolbox-38).

toolbox-run faithfully propagates the exit status of the command executed inside the container. This feature is vital for scripting, allowing external scripts to react appropriately to the success or failure of the containerized operation.

By default, commands are run as the current user inside the container, matching the user ID and home directory from the host system for a consistent experience, unless the --root option is used.

The toolbox project emerged from the need for a robust and mutable development environment on immutable Linux distributions like Fedora Silverblue. Initially known as podman-toolbox, the tool provided a consistent way to run developer tools and build systems within containers without altering the host operating system. toolbox-run was introduced as a key component to facilitate non-interactive execution of commands, complementing toolbox-enter for interactive sessions. This design decision empowers users to seamlessly integrate containerized development workflows into scripts and automation, significantly enhancing productivity and maintaining host system integrity.

toolbox(1), toolbox-enter(1), toolbox-create(1), podman(1)