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 push --runtime containerd docker.io/library/ubuntu:24.04 myuser/ubuntu:latest
sudo clipper pull --runtime containerd 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, not yours. 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 push --runtime containerd ...

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

Podman

podman pull ubuntu:24.04
clipper push --runtime podman ubuntu:24.04 myuser/ubuntu:latest
clipper pull --runtime podman 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.