You need a clean dev environment without breaking the host
You are working on a project that requires Python 3.11, but your host Fedora system is running 3.12. Or you are on Fedora Silverblue and the system refuses to let you install gcc because the OS is immutable. You need a development environment that matches your production server, but you want the comfort of VS Code, your desktop icons, and seamless file access. You do not want to manage a virtual machine or risk polluting your main system with conflicting libraries.
Toolbox solves this. It creates a rootful container based on a Fedora image that shares your user namespace and home directory. You get a clean shell where you can install whatever packages you need. The container integrates with your desktop session so GUI apps work. VS Code connects to the container and runs extensions inside it. Your host system stays untouched.
How Toolbox isolates your work
Toolbox is a wrapper around Podman. It simplifies container management for desktop development. When you create a toolbox container, the tool pulls a Fedora image and starts a container with specific settings. The container runs as root inside, but that root maps to your user ID on the host. This prevents privilege escalation. You cannot damage the host system by running commands inside the toolbox container.
The container mounts your /home directory. This means your files are accessible from both the host and the container. You do not need to copy files back and forth. The container also shares the host's network namespace by default. Ports you bind inside the container are visible on the host. This is convenient for testing web services. It also means you must manage port conflicts. If you bind port 8080 in the container, nothing else on the host can use 8080.
Toolbox handles systemd inside the container. You can run systemctl to manage services. The container runs a user session of systemd. This allows you to start background services that persist while the container is running. The container image matches your host release by default. If you are on Fedora 40, the container is Fedora 40. This ensures compatibility with host libraries and kernel features. You can specify a different release, but that introduces risk. Stick to the host release unless you have a specific reason to deviate.
VS Code integration relies on the Dev Containers extension. This extension runs on the host. It detects when you open a folder inside a container. It reconnects the editor process to the container. You get the full VS Code experience. Extensions run inside the container. The UI runs on the host. This separation keeps your development environment clean. You can install language servers and debuggers inside the container without affecting the host.
Run toolbox update regularly to refresh the container image. This command is separate from dnf upgrade on the host. Updating the container pulls the new base image and recreates the container. Your data in /home persists. Your installed packages persist. The base image refreshes with security patches and updates.
Check the container state before you start working. A stale container can cause dependency issues.
Set up Toolbox and connect VS Code
Install the toolbox CLI and Podman on your Fedora system. Toolbox provides the command-line interface. Podman is the container engine. On Fedora Workstation, these packages are often pre-installed. On minimal installs or Silverblue, you may need to install them.
Here is how to install the dependencies and create your first development container.
sudo dnf install toolbox podman
# WHY: toolbox provides the CLI wrapper. podman is the container runtime.
# On Silverblue, use 'flatpak install flathub org.fedoraproject.toolbox' if dnf fails.
toolbox create --name my-dev fedora
# WHY: Creates a container named my-dev based on the current Fedora release.
# The container image is pulled automatically if missing.
toolbox enter my-dev
# WHY: Drops you into a root shell inside the container.
# Your home directory is mounted and accessible.
Once the container is created, you can connect VS Code. Install the "Dev Containers" extension in VS Code on your host. This extension is required for the remote connection. Open VS Code and install the extension from the marketplace.
Here is how to launch VS Code connected to the container.
toolbox run --name my-dev code .
# WHY: Runs the VS Code command inside the container.
# The Dev Containers extension detects the container context and reconnects the editor.
# The dot opens the current directory in the container.
Alternatively, you can open a folder in VS Code on the host and select "Reopen in Container" from the command palette. VS Code will detect the toolbox container and attach to it. The status bar shows the container name. This confirms the connection is active.
If you want to customize the default container settings, edit the configuration file. Toolbox reads settings from ~/.config/containers/toolbox.conf. You can set the default image name or storage driver.
Here is an example configuration to pin the default image version.
# ~/.config/containers/toolbox.conf
[container]
# WHY: Sets the default image name for new containers.
# Use this to enforce a specific Fedora release for all new containers.
image = fedora-toolbox:40
[engine]
# WHY: Configures the Podman storage driver.
# vfs is safe but slower. overlay is faster and default on most Fedora systems.
# Only change this if you have storage performance issues.
storage-driver = overlay
Restart your terminal after changing the config. Toolbox reads the file on startup.
Reboot the container if you change the image config. Future containers will use the new settings.
Confirm the container is active
Verify that you are inside the container and that isolation is working. Run commands to check the hostname and package list. The hostname should match the container name. The package list should show only the packages installed in the container.
Here is how to verify the container environment.
toolbox enter my-dev
# WHY: Enter the container to verify isolation.
hostname
# WHY: Shows the container name.
# If this returns your host machine name, you are not in the container.
dnf list installed | grep gcc
# WHY: Confirms packages installed here do not affect the host system.
# If gcc is missing, you can install it without impacting the host.
whoami
# WHY: Shows your username.
# You are root inside the container, but your files are owned by your user.
Check the VS Code status bar. It should display the container name and the remote context. If you see a green icon with the container name, the connection is active. You can run terminal commands in VS Code. The terminal runs inside the container.
Run code . from the VS Code terminal to test file operations. Create a test file and save it. The file appears on the host filesystem. This confirms the mount is working correctly.
Check the hostname before you run dnf install. A wrong hostname means you are installing packages on the wrong system.
Common errors and configuration traps
Toolbox relies on Podman running as a user service. If Podman is not running, commands fail. You may see an error about the socket.
Error: cannot connect to Podman socket
This error means the user session service is not active. Start the service manually.
systemctl --user start podman
# WHY: Starts the Podman service for your user session.
# Toolbox requires this service to manage containers.
If the service fails to start, check the logs. Use journalctl to inspect the error.
journalctl --user -xeu podman
# WHY: Shows logs for the user Podman service.
# The -x flag adds explanatory text. The -e flag jumps to the end.
# Look for storage driver errors or permission denials.
SELinux can block access to mounted volumes. If you mount extra directories, you may need to set the correct context. Toolbox handles the default mounts automatically. Custom mounts require explicit context labels.
toolbox run --volume /path/to/project:/path/to/project:Z code .
# WHY: Mounts a volume with the :Z option.
# The :Z label relabels the content for exclusive use by the container.
# Use :z if multiple containers share the same directory.
GUI apps can cause configuration conflicts. Toolbox shares the home directory. If you run a GUI app in the container, it reads config from your home directory. The container app and host app share the same config. This can cause version mismatches. Be careful with GUI apps that write global state. Prefer running GUI apps on the host unless you need a specific version inside the container.
Services inside the container share the host network. Port conflicts are common. If you bind a port in the container, check if the host is using it.
ss -tlnp | grep 8080
# WHY: Lists listening ports on the host.
# Check for conflicts before starting services in the container.
If VS Code does not reconnect, check the extension. Ensure the Dev Containers extension is installed and enabled. Check the output log in VS Code for connection errors. The log shows the handshake between the host and container.
Read the actual error before guessing. Fabricating solutions wastes time.
Choose the right isolation tool
Different tools serve different workflows. Pick the tool that matches your isolation needs and team requirements.
Use Toolbox when you want a Fedora container that feels like the host, shares your home directory, and integrates with the desktop session.
Use raw Podman when you need to build images, run services with custom networking, or manage containers programmatically without the toolbox wrapper.
Use Docker when your workflow depends on Docker-specific CLI syntax or you are collaborating with a team that mandates Docker Desktop.
Use Nix when you need reproducible environments defined by code rather than a mutable container shell.
Stay on the upstream Workstation if you only deviate from the defaults occasionally and do not need strict isolation.
Pick the tool that matches your isolation needs. Toolbox is for development comfort. Podman is for container management.