The read-only wall
You booted Fedora Silverblue, opened the terminal, and typed sudo dnf install gcc. The package manager refused to cooperate. The output shows Error: Could not open locks or read-only filesystem. You are used to installing packages directly. This system stops you cold. You need a development environment, but the host system is sealed.
The host stays clean. The container takes the hits.
How containers solve the problem
Fedora Atomic editions like Silverblue and Kinoite use an immutable root filesystem. The base system is a sealed image. You cannot modify files in /usr or install packages directly to the system directories. The filesystem driver enforces this at the kernel level. If you try to write to /usr/bin, the kernel rejects the operation.
Think of the host system as a museum exhibit. You can look at it, you can interact with the displays, but you cannot rearrange the furniture or paint the walls. If you try to change the exhibit, the museum guards stop you immediately. Development requires changing things. You need a workshop.
Containers provide that workshop. They run on top of the museum, isolated but sharing the kernel and hardware. You can smash tools around in the workshop without damaging the exhibit. The container has its own mutable filesystem. You can install packages, modify configs, and break things inside the container. The host remains untouched. If the container breaks, you delete it and create a new one. The host is always safe.
Toolbox and Distrobox are the two main tools for creating these workshops. Both use Podman under the hood. Both mount your home directory so your files are accessible. Both forward X11 and Wayland so GUI apps work. The differences lie in integration and flexibility.
Run toolbox list or distrobox list to see what you have. If it's not there, you're on the host.
Setting up Toolbox
Toolbox is the official container tool for Fedora Atomic. It creates a container that mirrors the host Fedora release. The container looks and feels like a standard Fedora Workstation installation. You get the same package versions as the host, but with a mutable filesystem.
Here's how to create a Toolbox container that matches your host release.
# Create a toolbox container matching the host release
# The container inherits the host's package set and configuration
toolbox create --container dev-box
The --container flag sets the name. You will use this name to enter the container later. If you omit it, Toolbox generates a name based on the release. Explicit names are easier to remember.
Once created, enter the container to get a mutable shell.
# Enter the container to get a mutable shell
# Your home directory is mounted automatically
toolbox enter dev-box
Inside the container, the prompt changes to show the container name. You are now in a mutable environment. You can use dnf exactly as you would on Workstation.
# Install development tools inside the container
# This modifies the container filesystem only
sudo dnf install gcc make cmake
# Verify the installation
gcc --version
Toolbox integrates with the desktop. The container appears in the application menu. You can launch terminal sessions directly from the GUI. The integration is seamless for users who want a drop-in replacement for the standard development workflow.
Check the prompt. If the prompt doesn't show the container name, you are on the host. Don't force dnf on the host.
Setting up Distrobox
Distrobox offers more flexibility. It allows you to create containers with different Fedora versions or entirely different distributions. You can use Arch, Debian, or Alpine inside a Fedora Silverblue host. Distrobox also provides advanced features like host directory mapping and custom network configurations.
Here's how to create a Distrobox container with a specific Fedora image.
# Create a distrobox with a custom image
# --image allows you to pick any container image from a registry
distrobox create --name fedora-dev --image fedora:43
The --image flag pulls the base image from the container registry. You can specify any image available in the registry. This lets you test software on different Fedora releases or distributions without leaving the host.
Enter the container to start working.
# Enter the container to get a mutable shell
# Distrobox forwards environment variables for GUI apps automatically
distrobox enter fedora-dev
Inside the container, you have full control. Install packages, modify configs, and run tools.
# Install packages inside the container
# This is safe because the container filesystem is isolated
sudo dnf install python3 pip3 git
# Clone a project and build it
git clone https://github.com/example/project.git
cd project
make
Distrobox creates symlinks in ~/.local/bin on the host for executables installed in the container. This means you can run tools from the container directly on the host without entering the container. The integration is automatic.
Run distrobox list to see active containers. If the list is empty, create one before trying to enter.
Verifying the environment
You need to confirm that the container is working correctly and that the host remains immutable. The verification process checks both sides of the boundary.
Here's how to verify that tools are available inside the container but not on the host.
# Check that the tool is available inside the container
which gcc
# Exit the container to return to the host
exit
# Verify the tool is not on the host
which gcc
The output inside the container shows the path to the tool. The output on the host shows nothing. This confirms the isolation. The host is clean. The container has the tools.
You can also run commands inside the container from the host. This is useful for scripts that need the container environment.
# Run a container command from the host terminal
# This executes the command inside the container without entering it
distrobox enter fedora-dev -- gcc --version
The command runs inside the container and prints the version. The host never sees the binary. This pattern is common for CI scripts and automation.
Trust the package manager. Manual file edits drift, snapshots stay.
Common pitfalls and error messages
Errors usually happen when the boundary between host and container is crossed incorrectly. The most common mistake is trying to modify the host system.
If you run sudo dnf install on the host, you get this error:
Error: Could not open locks
Or this error:
read-only filesystem
These errors are expected. The host is immutable. You cannot install packages on the host. Use rpm-ostree for host updates. Use dnf inside the container.
Another common issue is GUI forwarding. If you try to launch a GUI app from the container and get XDG_RUNTIME_DIR not set, the session variables aren't forwarding correctly. Distrobox usually handles this automatically. Toolbox requires the toolbox wrapper for some GUI apps.
# Run a GUI app from the container using the toolbox wrapper
# This ensures environment variables are set correctly
toolbox run --container dev-box gedit
If a container fails to start, check the journal. The logs show why Podman rejected the operation.
# Check journal logs for container errors
# -xe adds explanatory text and jumps to the end
journalctl -xeu podman
The logs often show permission issues or missing dependencies. Fix the issue and recreate the container.
Convention aside: rpm-ostree upgrade updates the host system. dnf upgrade updates the container. They are different commands. Don't conflate them. The host uses rpm-ostree because the filesystem is immutable. The container uses dnf because the filesystem is mutable.
Check the prompt. If the prompt doesn't show the container name, you are on the host. Don't force dnf on the host.
Choosing your tool
The choice depends on your workflow and requirements. Both tools work well. The decision matrix helps you pick the right one.
Use Toolbox when you want a container that mirrors the host Fedora release exactly. Use Distrobox when you need a different Fedora version or a completely different distribution like Arch or Debian. Use Distrobox when you want to map specific host directories or use advanced podman features. Use Toolbox when you prefer the official integration with the Silverblue/Kinoite desktop environment. Use Distrobox when you need to run multiple containers with different configurations simultaneously. Use Toolbox when you want the simplest setup with minimal configuration.
Run toolbox list or distrobox list to see what you have. If it's not there, you're on the host.