Sign in

Container Runtimes

Clipper supports containerd, Podman, and Docker as container runtimes.

containerd (preferred)

Clipper communicates directly with the containerd API. This is the fastest option for pull because layers are applied directly to snapshots without a tar intermediary.

sudo clipper --runtime=containerd push docker.io/library/ubuntu:24.04 myuser/ubuntu:latest
sudo clipper --runtime=containerd pull myuser/ubuntu:latest

containerd typically requires sudo since the socket (/run/containerd/containerd.sock) is root-owned.

Note: When using sudo, clipper reads credentials from root’s home directory, but can fallback to your user directory. This may result in confusion if clipper is later run as root without SUDO_USER set. You need to run sudo clipper login separately, or set CLIPPER_CREDENTIALS_FILE to point to your credentials file:

sudo CLIPPER_CREDENTIALS_FILE=$HOME/.clipper/credentials.json clipper --runtime=containerd push ...

Clipper uses the moby namespace by default, which is the namespace Docker uses when running on containerd. This is overrideable via --namespace

Podman

podman pull ubuntu:24.04
clipper --runtime=podman push ubuntu:24.04 myuser/ubuntu:latest
clipper --runtime=podman pull myuser/ubuntu:latest

Rootful Podman requires sudo for both podman and clipper commands. Rootless Podman works without.

Docker

Clipper reads images via docker save and loads via docker load.

clipper push ubuntu:24.04 myuser/ubuntu:latest
clipper pull myuser/ubuntu:latest

Docker without the containerd image store is significantly slower. If you’re using Docker, we recommend enabling the containerd image store for best performance. With it enabled, clipper will auto-detect containerd and use the faster direct API path.

Auto-detection

Clipper auto-detects the available runtime in this order:

  1. containerd (if socket is available)
  2. Podman (if installed)
  3. Docker (fallback)

Use --runtime to override.