Toolbox

Summary

Toolbox is the developer-friendly container workflow for Fedora Atomic. It gives you a shell environment where you can install CLI tools, Git, package managers, and runtimes without turning the host itself into a normal mutable Linux system.

Why this matters

• Toolbox is usually the safest everyday place for development tools on Atomic
• it helps you keep the host cleaner and easier to recover
• if you install too much directly on the host, you lose the main advantage of the Atomic model

Environment / Scope

Item	Value
Platform	Fedora SWAY Atomic
Main tool	toolbox
Best use for this note	day-to-day developer workflow
Safe to test?	yes, in a lab
Related area	dev environment / CLI tooling / Linux workflow

Key concepts

• Toolbox - a convenient wrapper around container-based development environments
• Podman underneath - Toolbox uses Podman, but gives you a much friendlier workflow
• Host integration - Toolbox is designed to feel close to your normal user workflow
• Good use case - Git, Python, package installs, editors, CLI tooling, and experiments that should not live on the host

When to use Toolbox vs Podman

Use case	Better choice	Why
You want a dev shell for daily work	Toolbox	easiest workflow for user-level tooling
You need direct image / container lifecycle control	Podman	lower-level container control
You want Git, editors, language tools, package installs	Toolbox	better fit than changing the host
You want to expose ports or manage service-style containers	Podman	more natural for workloads than dev shells

Steps / Workflow

Workflow 1: create a toolbox

toolbox create dev
toolbox list

What happens:

1. toolbox create dev creates a toolbox named dev
2. Toolbox uses a Fedora-based image suitable for your host release
3. toolbox list lets you verify that the toolbox exists

Workflow 2: enter the toolbox

toolbox enter dev

Once inside, you can work more like a normal mutable Linux environment and install development tools without treating the host that way.

Workflow 3: do your normal CLI setup there

Examples:

sudo dnf install -y git openssh-clients wl-clipboard
git --version

Commands / Examples

Basic commands

toolbox list
toolbox create dev
toolbox enter dev

What they mean

Command	Meaning
toolbox list	show the toolboxes that already exist
toolbox create dev	create a toolbox called dev
toolbox enter dev	enter that toolbox shell

Important note

Toolbox does not replace Podman.
It uses Podman underneath, but gives you a better daily dev experience.

Verification

Check	Expected result
Toolbox exists	visible in toolbox list
Entry works	toolbox enter dev opens the toolbox shell
Tool install works	commands like git --version run successfully inside
Host stays cleaner	you are not layering normal dev tools directly on the host

Verification commands:

toolbox list
toolbox enter dev
git --version

Pitfalls / Troubleshooting

Problem	Likely cause	What to check
Toolbox command fails	Toolbox or container backend issue	Podman state, image availability
Toolbox exists but entry feels wrong	wrong toolbox name or stale environment	toolbox list, selected name
User expects Podman-style control	wrong mental model	Toolbox is for workflow, Podman is for raw container management
Host gets cluttered anyway	tools installed in the wrong layer	whether install happened on host or inside Toolbox

Common beginner trap

Toolbox feels convenient enough that you may forget it is still a container-backed workflow. That is fine, as long as you still remember its job is developer tooling, not full service orchestration.

Key takeaways

• Toolbox is usually the best first choice for daily CLI and development tooling on Atomic
• it is easier and safer than turning the host into a normal mutable Fedora install
• Podman still matters, but Toolbox is often the better user workflow for routine work

Official documentation

• Toolbx documentation
• Toolbx installation and getting started

Related

• Back to Fedora SWAY Atomic
• Fedora SWAY Atomic
• Podman
• Distrobox
• Git Setup
• Container Commands