Mirror and cache snapshots

Snapshots are hundreds of gigabytes. Keep a copy next to your GPUs, in your own registry or on the cluster's shared file system, and let every host pull from the nearest one.

Mirror into your registry

Copy one model, every platform this host can restore:

$ warmctl mirror glm53-flash oci://harbor.acme.internal/warmctl

Or the whole catalog, and the catalog list itself, for every platform:

$ warmctl mirror --catalog --all-platforms oci://harbor.acme.internal/warmctl

mirror copies registry to registry blob by blob, without touching the local disk, and skips what the destination already has, so running it again after a catalog update copies only what changed. Without --all-platforms it copies only the platforms this host can restore.

Mirror onto a shared file system

GPU clouds put a fast shared file system next to their nodes: the Nebius shared filesystem, Weka or VAST. Give mirror a directory instead of a registry:

$ warmctl mirror qwen3-8b /mnt/shared/warmctl

Each model becomes an OCI image layout under /mnt/shared/warmctl/<model>.

Point the hosts at the copies

On every GPU host:

registry: registry.warmctl.io/warmctl
mirrors: [harbor.acme.internal/warmctl]
cache: /mnt/shared/warmctl

up NAME and pull NAME now try the cache, then each mirror, then the registry. A snapshot downloaded from a registry is written into the cache on the way, so the next host reads it at file system speed. Kubernetes pods take the same settings from WARMCTL_REGISTRY, WARMCTL_MIRRORS and WARMCTL_CACHE.

Pull ahead of traffic

To make the first restore on a host as fast as the next, pull the snapshot before it is needed:

$ warmctl pull glm53-flash
$ warmctl images

A later up glm53-flash finds it pulled and goes straight to the restore. In Kubernetes, the node-prep DaemonSet does the same.

See also

• mirror, pull and Configuration in the reference.
• Use your own registry: credentials and registry quirks.