You need build tools but your host must stay clean
You installed Fedora Silverblue because you wanted a system that never breaks. You opened your editor, tried to build a project, and the compiler is missing. Or you are on Workstation and you just do not want fifty gigabytes of build dependencies cluttering your main system. You need gcc, cmake, and a dozen other tools, but you also need your host to stay pristine. The solution is toolbox. It gives you a mutable Fedora environment inside a container that shares your home directory. You get the full power of dnf without touching the host OS.
What's actually happening
Think of your host system as a museum. The exhibits are locked behind glass. You can look at them, and you can bring your own sketchbook to draw them, but you cannot rearrange the exhibits or paint on the walls. toolbox gives you a portable studio next to the museum. The studio has its own tools, paints, and materials. You can smash things, install weird packages, and break the build environment all you want. The museum stays untouched.
The magic is that your sketchbook sits on a table that spans both rooms. The container shares your $HOME directory via a bind mount. You edit a file in the studio, and the museum sees the change instantly. The container keeps /usr, /bin, and /etc separate. Packages installed inside the toolbox never appear on the host. The host never sees the container's packages. The isolation is strict for the system directories and transparent for your user files.
Create and enter the container
Here is how to spin up a new toolbox container. The command pulls the image that matches your current Fedora release and sets up the rootless podman backend.
# Create a container named after the current Fedora release.
# This is the default behavior and works for most users.
toolbox create
# Create a named container for a specific project.
# Naming helps when you manage multiple environments side by side.
toolbox create --container rust-project
Use this command to drop into the container shell. The prompt changes to show you are inside the container environment.
# Enter the default container.
# You now have a shell with full access to the container filesystem.
toolbox enter
# Enter a specific named container.
toolbox enter rust-project
You can use sudo inside the toolbox without fear. The container runs as a rootless podman container on the host. The sudo inside the container only grants privileges within that isolated namespace. It cannot affect the host system. This is a safe way to get root access for development tasks.
Install development tools
Inside the container, you have full root access via sudo. Install whatever you need. The packages exist only inside the container filesystem.
# Install the standard development group.
# This pulls in gcc, make, autoconf, and other build essentials.
sudo dnf groupinstall 'Development Tools'
# Install language-specific compilers and runtimes.
# These packages are isolated from the host system.
sudo dnf install gcc g++ cmake python3-devel nodejs golang
On immutable variants like Silverblue, you cannot install packages on the host at all. The root filesystem is read-only. toolbox is the only way to get a mutable environment with full package management. On Workstation, toolbox is optional but recommended for developers. It prevents dependency hell. You can have a Python 3.9 project in one container and a Python 3.12 project in another without conflicts. The host stays clean and upgradeable.
Run commands from the host
You do not always need to enter the shell. Run a single command inside the container and return to the host immediately. This is useful for scripts or CI pipelines that need specific tools.
# Execute a command inside the container and return to the host.
# This runs the command in the named container and prints the output.
toolbox run --container rust-project cargo build
# Run a command in the default container.
toolbox run gcc --version
The home directory mount is bind-mounted from the host. This means permissions and ownership are preserved. If you create a file in the toolbox, it appears on the host with your user ID. This is why editors like VS Code and Neovim work without configuration. They read the files from the host path, and the toolbox tools read the same files. The path is identical. You do not need to map ports or volumes manually.
Verify isolation
Verify the tool is installed in the container and absent on the host. This confirms the separation is working correctly.
# Check the version of gcc inside the toolbox.
# This should return a version number if the install succeeded.
gcc --version
# Exit the toolbox to return to the host shell.
exit
# Check for gcc on the host.
# This should return "command not found" on a clean system.
gcc --version
Trust the isolation. If the host says the command is missing, the host is safe.
Common pitfalls and errors
If you run toolbox create and see Error: container "fedora-toolbox-40" already exists, the container is already there. You do not need to create it again. Run toolbox enter instead. This error happens when you try to create a default container that was created in a previous session.
If you see toolbox: command not found on Workstation, install the package first. Run sudo dnf install toolbox. On Silverblue and Kinoite, toolbox ships by default. You do not need to install it.
If dnf fails inside the toolbox with a repository error, the container image might be stale. Run toolbox upgrade to refresh the container metadata. The container uses the same repositories as the host, but the metadata cache is separate.
Read the error message. "Already exists" means you are ready to enter, not that you need to create.
Maintenance and conventions
Manage your containers over time. Containers accumulate packages and updates. You should maintain them just like the host.
# List all toolbox containers and their states.
# This shows the container name, image, and creation date.
toolbox list
# Remove a container you no longer need.
# This deletes the container filesystem but preserves your home directory files.
toolbox rm rust-project
# Update the packages inside the container.
# Run this periodically to keep development tools secure and current.
toolbox upgrade
The toolbox environment inherits most environment variables from the host. This includes PATH, HOME, and USER. If you set custom variables in your ~/.bashrc or ~/.profile, they apply inside the toolbox as well. This ensures your shell configuration works consistently across both environments. You do not need to duplicate your dotfiles.
toolbox is a wrapper around podman. It automates the creation of a container that matches the host release and mounts the home directory. You can use podman directly, but toolbox handles the boilerplate. If you are comfortable with podman, you can inspect the container using podman ps or podman exec. The toolbox command simplifies the workflow for daily development. It knows how to name the container, how to mount the home directory, and how to set the environment variables correctly.
By default, toolbox passes through the X11 or Wayland display server socket. You can run graphical applications inside the toolbox and they will appear on the host desktop. This is useful for testing GUI applications or running IDEs inside the container. The integration is transparent. You do not need to configure X forwarding manually.
Update the container regularly. Stale tools cause build failures that look like bugs in your code.
When to use toolbox
Use Toolbox when you want a Fedora-matched environment that integrates seamlessly with the host home directory and system settings.
Use Distrobox when you need a container based on a different distribution, such as Ubuntu or Arch, or when you require features not available in the Toolbox CLI.
Use Flatpak when you are installing graphical applications and want strict sandboxing without needing a mutable shell environment.
Use the host system directly when you are running standard Workstation and do not mind installing packages globally.
Stay on the host when you need to modify kernel modules or access low-level hardware drivers that containers cannot reach.
Pick the tool that matches your isolation needs. More isolation means more friction.