toolbox-create(1)

✨ toolbox-create ✨

okay bestie, welcome to toolbox-create, section 1 of the General Commands Manual 🫶 this is the page that teaches you how to make a brand new Toolbx container, and honestly? it's giving main character energy. let's get into it 💅

---

🌸 NAME 🌸

toolbox-create — create a new Toolbx container 🎀

---

🦋 SYNOPSIS 🦋

toolbox create [--authfile FILE]
               [--distro DISTRO | -d DISTRO]
               [--image NAME | -i NAME]
               [--release RELEASE | -r RELEASE]
               [CONTAINER]

---

💖 DESCRIPTION 💖

so like, it creates a new Toolbx container. and then whenever you wanna go hang out inside it, you just hit up the toolbox enter command. any time. it's always there for you 🥰

a Toolbx container is an OCI container, and it gets created from an OCI image. on Fedora, the default image is called fedora-toolbox:N, where N is the release of the host. if that image isn't already sitting on your machine locally, it gets pulled from a well-known registry like registry.fedoraproject.org. other images can be used on other host operating systems, no gatekeeping. and if the host is like... not recognized at all? 🙈 then the Fedora image gets used anyway.

the container itself is created with podman create, and its entry point is set to toolbox init-container.

by default, a Toolbx container is named after its corresponding image, periodt. and if the image had a tag, that tag gets included in the container's name too — but it's separated by a hyphen, not a colon. (yes, really. hyphen. not colon. the way that matters 😭) you can assign a different name by using the CONTAINER argument.

🧚 Container Configuration

a Toolbx container seamlessly integrates with the rest of the operating system, bestie. it provides access to the user's home directory, the Wayland and X11 sockets, networking (including Avahi), removable devices (like USB sticks), the systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev database, etc.. iconic, truly ✨

the user ID and account details from the host get propagated into the Toolbx container, SELinux label separation is disabled, and the host file system can be accessed by the container at /run/host. the container also has access to the host's Kerberos credentials cache if it's configured to use KCM caches.

a Toolbx container can be identified by the com.github.containers.toolbox label or the /run/.toolboxenv file 👑

the entry point of a Toolbx container is the toolbox init-container command, which plays a role in setting up the container, along with the options passed to podman create.

🌈 Entry Point

a key feature of Toolbx containers is their entry point, the toolbox init-container command.

OCI containers are inherently immutable, no cap. configuration options passed through podman create are baked into the definition of the OCI container, and can't be changed later. which means changes and improvements made in newer versions of Toolbx can't be applied to pre-existing Toolbx containers created by older versions of Toolbx 😭 this whole situation is avoided by using the entry point to configure the container at runtime. slay.

the entry point of a Toolbx container customizes the container to fit the current user by ensuring that it has a user that matches the one on the host, and grants it sudo and root access 💅

crucial configuration files inside the container — /etc/host.conf, /etc/hosts, /etc/localtime, /etc/resolv.conf and /etc/timezone — are kept synchronized with the host. the entry point also bind mounts various subsets of the host's file system hierarchy to their corresponding locations inside the container, to provide seamless integration with the host. this includes /run/libvirt, /run/systemd/journal, /run/udev/data, /var/lib/libvirt, /var/lib/systemd/coredump, /var/log/journal and others.

on some host operating systems, important paths like /home, /media or /mnt are symbolic links to other locations. the entry point ensures that paths inside the container match those on the host, to avoid needless confusion. we love a tidy queen 🎀

---

⭐ OPTIONS ⭐

• --authfile FILE — path to a FILE with credentials for authenticating to the registry for private images. the FILE is usually set using podman login, and will be used by podman pull to get the image. the default location for FILE is $XDG_RUNTIME_DIR/containers/auth.json and its format is specified in containers-auth.json(5).
• --distro DISTRO, -d DISTRO — create a Toolbx container for a different operating system DISTRO than the host. cannot be used with --image. has to be coupled with --release unless the selected DISTRO matches the host.
• --image NAME, -i NAME — change the NAME of the image used to create the Toolbx container. this is useful for creating containers from custom-built images. cannot be used with --distro and --release. if NAME does not contain a registry, the local image storage will be consulted, and if it's not present there then it will be pulled from a suitable remote registry.
• --release RELEASE, -r RELEASE — create a Toolbx container for a different operating system RELEASE than the host. cannot be used with --image.

---

🔥 EXAMPLES 🔥

🌸 Create the default Toolbx container matching the host OS

$ toolbox create

🌸 Create the default Toolbx container for Fedora 36

$ toolbox create --distro fedora --release f36

🌸 Create a custom Toolbx container from a custom image

$ toolbox create --image bar foo

🌸 Create a custom Toolbx container from a custom image that's private

$ toolbox create --authfile ~/auth.json --image registry.example.com/bar

---

👑 SEE ALSO 👑

toolbox(1), toolbox-init-container(1), podman(1), podman-create(1), podman-login(1), podman-pull(1), containers-auth.json(5)

---

okay that's the whole page bestie 🫶 the footer just says toolbox-create(1) and honestly? that's her. that's the whole vibe. go make yourself a container, you absolute icon 💖✨🎀🦋