Skip to main content
Template warm pools keep tenant-owned ready capacity for a template. Use them when you expect a burst of machines from the same prepared environment and the template start_cmd plus readiness probes already produce the state each machine should start from. Warm pools do not preserve per-run mutable state. A checkout claims one ready VM and turns it into a normal machine; it is not recycled back into the pool after use. Keeping a pool warm reserves runtime capacity. Treat min_ready, max_ready, CPU, and memory as cost-bearing choices, and drain or delete pools when the burst ends.

​
Create A Pool

Build or identify a template first, then create a pool with public readiness targets:
If you already have a template object, Template.create_warm_pool(...) is a convenience wrapper around TemplateWarmPool.create(...). The equivalent CLI flow uses --json for automation:
The HTTP API surface is /v1/template-warm-pools with create, list, get, update, delete, status, enable, disable, drain, and reconcile operations. Tenant pool placement scope is all-or-none. When a pool sets host_pool_id or cell_id, both fields must be present and the resolved template must provide a compatibility key. Partial scope is rejected so checkout cannot claim ready inventory from a mismatched host class.

​
Create From A Pool

Pass the explicit pool ID when creating machines:
warm_pool_checkout is present when create considered a warm pool. It reports source, hit, id, and mode so callers can distinguish a ready checkout from a cold fallback or explicit bypass.

​
Checkout Modes

Use prefer for general latency improvement and require when the work should only run if ready capacity is available. In the CLI, pass --warm-pool-mode require for the latter behavior.

​
Poolable Shape

Template start_cmd and readiness are the pool startup contract. The command runs during template build before snapshotting, and warm pools restore that ready template state. create-time envs, volume mounts, cwd overrides, desktop settings, custom networking, non-destroy timeout policy, and auto-resume are not poolable startup state. In prefer mode, unsupported create-time shape falls back to a cold create. In require mode, it fails with warm_pool_unavailable. snapshot restore, resume, fork, hibernate, and pause do not use template warm-pool checkout. Use reusable snapshots or fork when you need mutable state captured from a running machine, hibernate or auto-resume when one machine should pause and continue later, and volumes when data must persist across machine cleanup.

​
Version Policy

pinned_build pools resolve the template ref to one build and continue filling that build until updated. track_tag pools follow a template tag. When the tag moves, the pool records a new rollout generation, stops filling old ready or warming inventory, drains old ready rows, and fills the new build. Machines already claimed from the old build continue as normal user machines.

​
Status And Troubleshooting

Inspect status before a burst:
Status counts are target, ready, warming, claimed, draining, failed, expired, and unavailable. Common degraded reasons: If a burst must not cold start, use require and handle warm_pool_unavailable explicitly. If cold fallback is acceptable, use prefer and inspect warm_pool_checkout.source after create.

​
Drain And Delete

Drain a pool when the burst ends or before replacing it:
Draining stops refill and releases ready inventory over the normal controller budget. Deleting a pool requests drain; it does not destroy machines that were already checked out.