Toolbox

Toolbox (Toolbx) is an integral part of Fedora Atomic, being one of the main methods of installing software, it lets you run your applications inside of Podman containers. Toolbox can actually be used on any Linux system that is capable of running Podman, but it is especially useful on Atomic hosts. Toolbox is more tightly integrated with your host OS than Docker or Podman containers normally are. Toolbox containers share the same /home directory with the host (bind mounted), and they live in the same network and process namespace as the host (ie. you can run ps or kill from inside the toolbox, and it will see/affect the host.) Toolbox containers are not sandboxed like normal Docker containers are, but they are a convenience for installing/removing software on Atomic hosts, since the host filesystem is read-only (but read-write inside of a container). The applications you install in the container will live only inside the toolbox.

The killer feature of a toolbox is that it lets you try things out, and if you want to start over, you can just delete the toolbox container, and create a new one. You are less likely to mess up the host by playing around inside the toolbox. Just remember that /home is bind mounted to the host, and so if you change or delete things in those directories, they are also affected the same way on the host.

Dev toolbox (Fedora)

Let’s create a toolbox to install some of the common development tools we will use on a daily basis.

## Automatic install:
dev-install

## Alias to enter the container:
dev

## Manual install:
toolbox create dev

This will create a new toolbox container called dev.

By default, the container image that toolbox selects is the same OS version as the host. (eg. If the host is running Fedora Atomic Sway 40, the toolbox will run Fedora Workstation 40.)

To enter the toolbox run:

## Manual method:
toolbox enter dev

This will enter the toolbox container, and now you can install extra software:

## Manual install:
##
sudo dnf install keychain htop gettext libwebp-tools flatpak-xdg-utils
sudo dnf groupinstall "Development Tools" "Development Libraries"

sudo ln -s /usr/bin/flatpak-xdg-open /usr/local/bin/xdg-open

Arch Linux toolbox

You are not limited to using the default toolbox image, in fact you can run any container image you want, or even build your own from a Dockerfile. Here is how to build a custom Arch Linux container image:

## Automatic install:
arch-dev-install

## Alias to enter container:
arch-dev

## Manual install:
##
IMAGE=arch
(set -e
mkdir -p ~/toolbox/${IMAGE}
cat << 'EOF' > ~/toolbox/${IMAGE}/Dockerfile
## http://book.rymcg.tech/linux-workstation/config/toolbox/#arch-linux-toolbox
FROM docker.io/archlinux/archlinux:latest
ENV NAME=arch-toolbox VERSION=rolling
LABEL com.github.containers.toolbox="true" name=${IMAGE}-toolbox
RUN pacman -Syu --noconfirm \
    && pacman  -S --noconfirm sudo inetutils less \
       git base-devel go \
       noto-fonts noto-fonts-cjk \
       noto-fonts-emoji noto-fonts-extra \
    && pacman -Scc --noconfirm \
    && echo "%wheel ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/toolbox
RUN sudo -u nobody git clone https://aur.archlinux.org/yay-bin.git /tmp/yay \
    && cd /tmp/yay \
    && sudo -u nobody makepkg -s \
    && pacman -U --noconfirm yay-bin-*.pkg.tar.zst
CMD ["bash"]
EOF
podman build -t ${IMAGE} ~/toolbox/${IMAGE}
)

Now you can create a new toolbox based on the new image (both called arch):

## Manual install:
##
toolbox create --image arch arch

To enter the Arch Linux container, run:

## Manual method:
toolbox enter arch

Now that you’re inside the toolbox, you can run any Arch Linux command (consult the Arch Wiki).

## Manual install:
##
sudo pacman -Syu
sudo pacman -S keychain base-devel

Managing toolbox containers

You can list all of your toolboxes that you’ve created:

toolbox list

You can remove existing toolboxes:

toolbox rm --force arch

(force is only required if the toolbox is currently running.)

Host spawn

host-spawn is a program you can install inside of a toolbox, to run commands on the host.

Install host-spawn inside Fedora container

## Manual install:
##
sudo dnf install host-spawn

Install host-spawn inside Arch Linux container

## Manual install:
##
(set -e
BUILD_DIR=~/aur/host-spawn
rm -f ${BUILD_DIR}/*.zst
mkdir -p ${BUILD_DIR}
cat << 'EOF' > ${BUILD_DIR}/PKGBUILD
pkgname=host-spawn-git
pkgver=v1.6.0.r0.ge150d2c
pkgrel=1
pkgdesc='Run commands on your host machine from inside your flatpak sandbox, toolbox or distrobox containers.'
arch=('any')
url="https://github.com/1player/host-spawn"
license=('MIT-0')
source=("${pkgname%-git}::git+https://github.com/1player/host-spawn.git")
depends=('go')
makedepends=('git')
conflicts=("${pkgname%-git}")
provides=("${pkgname%-git}")
package() {
  cd "${pkgname%-git}"
  ./build.sh $(uname -m)
  install -Dm 555 build/host-spawn-$(uname -m) \
    "${pkgdir}"/usr/bin/host-spawn
}
pkgver() {
  cd "${pkgname%-git}"
  git describe --long --tags | sed 's/\([^-]*-g\)/r\1/;s/-/./g'
}
sha256sums=('SKIP')
EOF
cd ${BUILD_DIR}
makepkg
sudo pacman -U host-spawn-*.zst
)

Run host programs

Once you install host-spawn inside your container, you can use it to run any host command:

host-spawn toolbox list

This will invoke toolbox on the host.

Create host program shims

## Manual install:
##
sudo ln -s /usr/bin/host-spawn /usr/local/bin/toolbox
sudo ln -s /usr/bin/host-spawn /usr/local/bin/distrobox
sudo ln -s /usr/bin/host-spawn /usr/local/bin/podman
sudo ln -s /usr/bin/host-spawn /usr/local/bin/flatpak

This will allow you to run the host programs toolbox, podman and flatpak, from inside the container, without needing to run host-spawn directly.