You need a mutable workspace on an immutable desktop
You switched to Fedora Silverblue to stop fighting package conflicts and enjoy atomic rollbacks. You open a terminal to install a specific version of Go or a C++ compiler, and the package manager tells you to reboot. You need a mutable development environment, but you refuse to break the sealed base image.
How the overlay actually works
Silverblue treats the root filesystem as a sealed artifact. The rpm-ostree transaction model merges packages into a single read-only layer. Installing a development tool triggers a full system update, downloads a new boot tree, and requires a restart. That workflow works for system services. It breaks developer velocity.
Toolbox solves this by launching a standard Fedora container that shares your user ID and mounts your home directory directly. The container runs with a mutable overlay filesystem. You get a full dnf experience inside it. The host system stays untouched. Think of it as a portable workbench that plugs into your existing desk. You keep the clean base image. You get the messy compiler cache you need.
The overlay driver writes changes to a separate storage layer under ~/.local/share/containers/storage/. When you exit the container, those changes commit to disk. When you re-enter, the driver layers the committed changes over the base image. The host never sees the modifications. The container never touches the host root.
Convention aside: always run dnf upgrade --refresh inside the toolbox after a host update. The container pulls its own repository metadata independently. Keeping the container packages current prevents dependency drift when you compile against host libraries.
Creating and entering your development container
Toolbox ships with Fedora Silverblue by default. Verify it is present before creating your first workspace.
toolbox --version
# Confirms the CLI is installed and reports the current release
# Missing output means the package was removed during a custom rebase
Create a new development container. The command pulls the latest Fedora release image, configures the storage driver, and drops you into a shell.
toolbox create --name dev --distro fedora
# --name assigns a human-readable label for later entry
# --distro pins the container to the current Fedora release stream
# The command automatically detects podman as the backend engine
Enter the workspace whenever you need to compile code or run a local server.
toolbox enter dev
# Attaches your terminal to the running container process
# Preserves your $HOME path and user permissions across the boundary
Once inside, you can install packages without touching the host. The container uses standard dnf transactions. Changes persist across sessions because the overlay filesystem commits to disk on exit.
dnf install gcc make git
# Runs a standard mutable transaction inside the container
# Packages install to /usr/bin without triggering a host reboot
Managing the container lifecycle
Containers run as background processes tied to your user session. You can pause, resume, or remove them without losing data.
toolbox list
# Shows all created containers, their current state, and base image
# Use this to verify which workspace is active before entering
toolbox pause dev
# Suspends the container process and releases CPU resources
# The overlay filesystem remains intact on disk
toolbox resume dev
# Restores the container to its previous running state
# All in-memory caches and open file descriptors are preserved
toolbox rm dev
# Deletes the container metadata and overlay storage
# Your host home directory files remain untouched
Reboot before you debug. Half the time the symptom is gone.
Networking and port exposure
The container shares the host network namespace by default. You can bind to localhost ports and access them directly from the host browser or terminal.
node server.js
# Starts a local development server inside the container
# Listens on 127.0.0.1:3000 by default
curl http://127.0.0.1:3000
# Runs from the host terminal to verify the port is reachable
# Confirms network namespace sharing is working correctly
If you need to expose a port to external machines, configure the host firewall before starting the service.
sudo firewall-cmd --add-port=3000/tcp --permanent
# Adds a persistent rule to the host firewall configuration
# --permanent ensures the rule survives a network manager reload
sudo firewall-cmd --reload
# Applies the persistent rules to the active runtime configuration
# Runtime and persistent configs diverge if you skip this step
Run ss -tlnp first. Read the actual listening sockets before guessing.
Storage limits and disk management
The overlay filesystem grows as you install packages and compile projects. Unchecked growth fills your home partition and breaks container startup.
podman system df
# Reports disk usage for images, containers, and local volumes
# Shows the total size of your toolbox overlay layers
podman system prune -a
# Removes unused images, stopped containers, and dangling layers
# Frees space without deleting your active toolbox containers
Convention aside: config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The same rule applies inside the container. Keep your project configuration in ~/.config/ or your repository root. Let the package manager handle system paths.
Verify it worked
Confirm the container is isolated from the host root but shares your user environment. Run these checks immediately after entering.
cat /etc/os-release
# Shows the container's Fedora release version
# Should match the host or lag by one minor release depending on pull time
ls -ld /home/$USER
# Verifies your host home directory is bind-mounted into the container
# Permissions must match your UID to avoid permission denied errors on project files
which dnf
# Returns /usr/bin/dnf inside the container
# Confirms you are using the mutable package manager, not rpm-ostree
Reboot the host and run toolbox enter dev again. Your installed packages and compiled binaries will still be there. The overlay filesystem survives container restarts.
Common pitfalls and what the error looks like
Toolbox relies on podman and fuse-overlayfs. Missing components or misconfigured storage drivers cause silent failures or hard errors.
If the container engine is not running, the create command aborts immediately.
Error: cannot connect to Podman. Is Podman running?
Start the background service and retry.
systemctl --user start podman.socket
# Activates the on-demand podman socket for your user session
# Silverblue uses socket activation to keep the daemon lightweight
Storage driver mismatches appear when fuse-overlayfs is missing or blocked by a strict security policy. The error usually surfaces during the initial pull.
Error: creating container storage: overlay: applyDiff: applying diff: exit status 1: mkdir /var/home/.local/share/containers/storage/overlay: permission denied
Install the missing driver on the host system.
sudo dnf install fuse-overlayfs
# Provides the FUSE-based overlay driver required for rootless containers
# Reboot the host to load the kernel module and refresh container storage paths
SELinux denials occasionally block container access to specific host directories. Check the audit log before relaxing policies.
journalctl -t setroubleshoot | tail -n 5
# Shows one-line summaries of SELinux policy violations
# Look for messages referencing container_t or fuse_t contexts
If you see [FAILED] Failed to start podman.service during boot, your container storage directory probably has incorrect ownership. Fix the permissions on the host before restarting the socket.
Run podman system info first. Read the actual storage driver and graph root path before guessing.
When to use this vs alternatives
Use Toolbox when you need a mutable development environment that shares your host user ID and home directory. Use native Silverblue packages when you only need a few system utilities that do not conflict with the base image. Use rpm-ostree install when you are adding a permanent system dependency that must survive a full OS rebase. Use a full virtual machine when you need to test a different kernel, modify low-level network namespaces, or run software that requires root access to the host hardware. Stay on the upstream Silverblue image if you only deviate from the defaults occasionally.