CLI
warmctl <command> [flags]. Positional arguments come first, flags after them. Run it as root on the GPU host; catalog --all, images oci://… and mirror --all-platforms also work from a machine without GPUs.
| Command | What it does |
|---|---|
| build | bake a warmed engine into a snapshot |
| up | serve a snapshot, pulling it first when needed |
| ps · down | list the instances serving on this host; stop one |
| catalog | list the registry's models this host can restore |
| images | list the snapshots on this host, or a repository's tags |
| push · pull | move snapshots through an OCI registry or a directory |
| mirror | copy models into another registry or a shared directory |
| verify · gc | check a snapshot against its manifest; remove unused blobs |
| doctor | check this host |
| profile | list, check and show profiles |
Naming a snapshot
Wherever a command takes a snapshot, it accepts any of these:
| Form | Means |
|---|---|
qwen3-8b | a repository in the configured registry: registry.warmctl.io/warmctl/qwen3-8b by default; its latest index, from which the host's platform is taken |
qwen3-8b:TAG | one platform tag of it, skipping the choice |
ghcr.io/acme/qwen3-8b[:TAG] | a repository in another registry: the first part has a dot, a colon or is localhost |
oci://REGISTRY/REPO[:TAG] | the same, spelled out |
/snaps/qwen3-8b | a snapshot directory on this host |
dir:/mnt/shared/warmctl | a directory of OCI image layouts, for push, pull and mirror |
Shared flags
Engine flags: build, up
| Flag | Default | |
|---|---|---|
| --state-dir DIR | /var/lib/warmctl | snapshots, blobs, instances and locks |
| --docker PATH | /var/run/docker.sock | Docker socket |
| --progress FORMAT | plain | plain or jsonl, one JSON object per event |
| --no-verify | a canary mismatch only warns | |
| --threads N | 4 | weights copy threads per GPU |
| --cuda-execution MODE | auto | GPU state restore: auto, serial or parallel |
| --criu PATH | a host CRIU binary instead of the image's | |
| --cuda-checkpoint PATH | a host cuda-checkpoint instead of the image's | |
| --test-cpu | end-to-end test on a CPU host: no GPU devices, no io_uring check |
Registry flags: up, push, pull, mirror, images
| Flag | Default | |
|---|---|---|
| --concurrency N | 64 | blobs transferred at once |
| --plain-http | talk to the registry over plain HTTP |
Credentials come from Docker's (docker login). Where short names resolve: Configuration.
build aliases: snapshot, bake
warmctl build --profile ID|FILE --model-dir DIR --output DIR [--gpus LIST] [flags]
Starts vLLM in a container with the profile, warms it over every shape the profile declares, records the canary and checkpoints the processes, the GPUs and the weights into a new snapshot directory.
| Flag | Default | |
|---|---|---|
| --profile ID|FILE | a built-in profile id or a YAML file; required | |
| --model-dir DIR | the weights on this host; required | |
| --output DIR | the snapshot directory to create; required | |
| --gpus LIST | GPU indices, e.g. 0 or 0-7 | |
| --set KEY=VALUE | override the profile: vllm.<flag>=…, env.<NAME>=… or ipc=<mode>; repeatable | |
| --profile-dir DIR | another directory of profile files; repeatable | |
| --id NAME | output's name | run id |
| --ready-timeout DUR | 90m | how long the engine may take to load |
| --part-bytes N | 1 GiB | size of a weights part |
| --cuinterpose DIR | next to warmctl | the cuInterpose build |
$ warmctl build --profile glm53-flash-prod-tp8 --model-dir /models/glm --gpus 0-7 --output /snaps/glm
up alias: restore
warmctl up SNAPSHOT [flags]
Resolves the snapshot (pulling the platform that fits this host), checks the host, restores the engine, runs the canary and serves an OpenAI-compatible API until it is stopped. In the warmctl runtime image it restores in place, in its own container: Run in Kubernetes.
| Flag | Default | |
|---|---|---|
| --listen ADDR | 127.0.0.1:8000 | gateway address; :8080 in place |
| --gpus LIST | first free | GPU indices; by default the first free GPUs of the snapshot's model |
| --id NAME | snapshot's name | instance id, for ps and down |
| --canary POLICY | profile's | bitwise, tolerance, warn or off |
| --verify-weights | check each weights part's SHA-256 while reloading | |
| --model-dir DIR | the weights, when the snapshot needs them | |
| --accept-license | accept the license of a model the catalog marks gated | |
| --mode MODE | auto | auto, host (Docker) or in-place |
| --run-dir DIR | /run/warmctl | in place: the agent's config, sockets and work |
Plus the engine and registry flags.
$ warmctl up glm53-flash --listen 0.0.0.0:8000 $ warmctl up /snaps/qwen3-8b --gpus 3 --id qwen-a --listen :8001
ps
warmctl ps [--all]
Lists the instances serving on this host: id, status, address, uptime and snapshot. --all adds those whose container stopped. Also --state-dir, --docker.
down alias: stop
warmctl down ID [--grace DUR]
Stops an instance, giving the engine --grace (30 s) to finish. Also --state-dir, --docker.
catalog
warmctl catalog [--all] [--json]
Lists the models the configured registry publishes, one row per platform this host can restore, with size, status (ready in the registry, pulled on this host) and license.
| Flag | Default | |
|---|---|---|
| --all | also the platforms this host cannot restore, with the reason | |
| --json | print JSON | |
| --publish FILE | publish a catalog YAML file as <registry>/catalog:latest |
images alias: ls
warmctl images [oci://REGISTRY/REPO]
Without an argument, the snapshots on this host. With a repository, its tags.
push
warmctl push DIR NAME|REGISTRY/REPO|oci://REGISTRY/REPO[:TAG] [flags]
Stores a snapshot as one OCI artifact under its platform tag and adds it to the repository's latest. Large files go as 64 MiB pieces, runs of small files as bundles.
| Flag | Default | |
|---|---|---|
| --piece-size SIZE | 64MiB | split files larger than this into layers of this size |
| --chunk-size SIZE | 0 | upload larger blobs in chunks of this size; 0 chunks only after the registry refuses a blob as too large |
pull
warmctl pull SNAPSHOT [--output DIR]
Downloads the platform this host can restore, checking each piece and file, and prints the snapshot directory (<state>/pulled/<digest> by default). Tries the cache, the mirrors, then the registry; resumes after an interruption.
mirror
warmctl mirror SNAPSHOT DESTINATION warmctl mirror --catalog DESTINATION
Copies a model, or every model of the catalog and the catalog itself, into a registry namespace (oci://harbor.acme/warmctl) or a directory (/mnt/shared/warmctl), blob by blob, skipping what is there.
| Flag | Default | |
|---|---|---|
| --catalog | copy every model of the registry's catalog | |
| --all-platforms | every platform, not only those this host can restore |
verify
warmctl verify DIR [--deep]
Checks that every file in manifest.json is present with its size; --deep also hashes each against its SHA-256.
gc
warmctl gc [--dry-run]
Removes blobs from the store that no recorded snapshot uses. --dry-run only reports them.
doctor
warmctl doctor
Checks Docker, the GPUs and driver, kernel.io_uring_disabled, the NVIDIA runtime and the kernel; one line per check, non-zero exit if any fails.
profile
warmctl profile list|check [--dir DIR] warmctl profile show|argv ID|FILE [--dir DIR]
list prints the profile ids, check resolves every profile against the hardware table, show prints a profile with its defaults applied and its warmup cases as JSON, argv the vllm serve command it runs. Format: Profiles.
version
warmctl version