From ArchWiki

Toolbox is a tool that allows you to create and run containers that seamlessly integrate with the rest of the operating system by providing access to the user's home directory, the Wayland and X11 sockets, networking (including Avahi), removable devices (like USB sticks), systemd journal, SSH agent, D-Bus, ulimits, /dev and the udev database, etc.


Install the toolbox package.

Note that podman is installed as a dependency of Toolbox. By default it is only possible to run Podman containers as root. See Podman#Rootless Podman to set up running containers as a non-root user. In general, if you are having issues with Toolbox, make sure your issues are not with Podman first.

If you want to build your own toolbox-compatible images, install buildah as well.

Fedora Containers

You can create a Fedora 35 toolbox with the following:

$ toolbox create -d fedora -r 35

Once that's done, you can enter the toolbox with:

$ toolbox enter fedora-toolbox-35

Arch Containers

There is currently no upstream image for Arch Linux toolbox containers, but you can build your own if you have buildah installed.

Save the following to a Dockerfile:

ENV NAME=arch-toolbox VERSION=rolling
LABEL com.github.containers.toolbox="true" \
  name="$NAME" \
RUN pacman -Syu --noconfirm \
  && pacman -S sudo --noconfirm \
  && pacman -Scc --noconfirm \
  && echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/toolbox
CMD ["bash"]

Build the image:

$ cat Dockerfile | podman build -t arch-toolbox -

Create the Toolbox container:

$ toolbox create --image arch-toolbox
Tip: In this example, the toolbox container is named after its corresponding image. If you want to manage multiple Arch-based toolboxes, you can assign a different name with an additional argument here.

Once that's done, you should be able to enter the toolbox with:

$ toolbox enter arch-toolbox


X11 applications not starting

When attempting to run an X11 application from within the toolbox, you may get the following error:

Authorization required, but no authorization protocol specified
Error: Can't open display: :0

To fix this, you can use xorg-xauth (on your host machine) to give your container permission to communicate with X11. Run the following, or add it to Xinit#xinitrc:

$ xauth add "toolbox/unix$DISPLAY" . "$(xauth list | grep "^$(hostname)/unix$DISPLAY\s*MIT-MAGIC-COOKIE-1\s*" | awk '{print $3}')"

Alternatively, run:

$ xauth nlist | sed -e 's/^..../ffff/' | xauth nmerge -

See also