Container Runtime Setup

boks requires a container runtime: Podman (recommended) or Docker.

Podman

Linux

Install from your distribution's package manager:

# Debian/Ubuntu
sudo apt install podman

# Fedora
sudo dnf install podman

# Arch
sudo pacman -S podman

Verify the install:

podman --version

macOS

Install Podman Desktop from podman.io. After installation, start the Podman machine before using boks:

podman machine init    # first time only
podman machine start
podman --version

The machine must be running whenever you use boks.

Docker

If Docker is already set up, boks works with it out of the box — when Podman is not installed, boks falls back to Docker automatically. To use Docker even when Podman is present, pass --runtime docker or set it in boks.toml:

[global]
runtime = "docker"

Any Docker Engine or Docker Desktop installation works; boks talks to the docker CLI. Note that Docker does not support Podman's --userns=keep-id, so files created in --cap rw mode may be owned by a different UID than yours on Linux.

Runtime detection

When no --runtime flag is given and no runtime is set in the config, boks uses Podman if it is installed, and otherwise falls back to Docker. If neither is on your PATH, the welcome screen reports it; install one before running any tool.

Precedence: --runtime flag > [global] runtime in boks.toml > auto-detect.

Supported values for --runtime: