Reference
Configuration
Three settings say where snapshots come from. Everything else is a flag, a profile or a fixed path on the host.
config.yaml
registry: registry.warmctl.io/warmctl mirrors: [harbor.acme.internal/warmctl] cache: /mnt/shared/warmctl
| Key | Default | |
|---|---|---|
registry | registry.warmctl.io/warmctl | registry host and namespace where short names resolve: up qwen3-8b pulls <registry>/qwen3-8b |
mirrors | none | registries holding copies of its repositories, tried before it, in order |
cache | none | a directory of OCI image layouts, usually on a shared file system, tried first and filled on every download |
Read in order, each overriding the keys it sets: /etc/warmctl/config.yaml, then ~/.config/warmctl/config.yaml, then the environment. Unknown keys are an error.
Environment
| Variable | Overrides |
|---|---|
WARMCTL_REGISTRY | registry |
WARMCTL_MIRRORS | mirrors, comma separated |
WARMCTL_CACHE | cache |
Registry credentials
warmctl reads Docker's credential store and helpers, as docker login writes them (~/.docker/config.json of the user running it, root on a GPU host). The public registry needs none.
Paths on the host
| Path | |
|---|---|
/var/lib/warmctl | the state directory (--state-dir) |
blobs/sha256/ | content-addressed files shared by every snapshot |
pulled/<digest>/ | snapshots pulled from a registry |
restores/<id>/ | a running instance: instance.json for ps and down |
logs/<id>/ | logs of a build or a restore |
locks/ | GPU leases: two restores never share a GPU |
/run/warmctl | in place, in a pod: the agent's config, sockets and work (--run-dir) |
/var/run/docker.sock | the Docker API (--docker) |
The gateway
A restored engine is reached only through warmctl's gateway, which listens on 127.0.0.1:8000 on a host (--listen) and :8080 in a pod.
| Route | |
|---|---|
POST /v1/chat/completions | OpenAI-compatible inference |
POST /v1/completions | OpenAI-compatible inference |
GET /v1/models | the served model names from the profile |
GET /metrics | vLLM's Prometheus metrics |
GET /health | 503 until the canary passed, 200 after |
Every other route, including vLLM's sleep, wake and RPC endpoints, answers 404. Request bodies are capped at 16 MiB.