Toolbox - ArchWiki

Jump to content

Related articles

- Linux Containers
- Podman
- Buildah

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.

## Installation

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:

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

Tip: If `archlinux/archlinux` fails to be resolved, make sure that "docker.io" is already listed under `unqualified-search-registries` in `/etc/containers/registries.conf`

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

## Troubleshooting

### X11 Apps Not Working

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

- Official website
- Github repo
- Fedora Silverblue documentation
- toolbx-images - Community maintained container images to use with Toolbox, with pre-built images available via quay.io
- duhdugg's custom toolboxes - a set of custom scripts to build toolbox containers using a directory structure that makes them simple to modify

Categories:

- Virtualization
- Sandboxing