#Warm Pool

Sandbox0 achieves sub-200ms sandbox creation by maintaining a pool of pre-warmed idle pods for each template. When you claim a sandbox, an idle pod is immediately assigned instead of waiting for a cold container start.

How the Pool Works#

When a sandbox is claimed:

The manager first tries to claim a running idle pod (claimIdlePod)
If successful (hot claim), the pod is relabeled to active and returned immediately; pool replenishment happens asynchronously via ReplicaSet reconcile
If no idle pod exists (cold claim), the manager directly creates a new active pod (createNewPod) and asynchronously triggers scale-up (OnColdClaim) to rebuild idle capacity

As long as minIdle idle pods are available, every claim is a zero-cold-start operation.

Pool Fields#

Configure the pool strategy in your template spec under the pool key:

Field	Type	Description
`minIdle`	integer	Minimum number of idle pods to maintain (ReplicaSet replicas). Claims always succeed instantly while idle pods are available.
`maxIdle`	integer	Maximum number of idle pods allowed for autoscaling decisions. The autoscaler caps scale-up at this value, and template status reports `PoolHealthy=False` if idle pods exceed it.

yaml
spec:
    pool:
        minIdle: 3
        maxIdle: 10

minIdle — Guaranteed Fast Starts#

minIdle is the number of idle pods the system keeps running at all times. The manager's ReplicaSet controller continuously reconciles towards this count:

If idle pods drop below minIdle (due to claims), new pods start immediately
If the node has capacity, minIdle pods are pre-warmed and ready before any request arrives

Choosing minIdle:

Workload Pattern	Recommended `minIdle`
Low traffic / dev environments	1–2
Steady interactive traffic	3–5
Burst-heavy production	5–20+
Single-user tool	1

ℹ

Each idle pod consumes CPU and memory as defined in mainContainer.resources. Setting minIdle too high wastes cluster resources. Monitor your claim rate and set minIdle to match your typical concurrency.

maxIdle — Capping Idle Resources#

maxIdle puts an upper bound on idle pool size for autoscaling decisions. The autoscaler uses it as a hard cap when deciding target replicas:

Prevents scale-up from growing beyond a configured ceiling
Works with template status conditions (PoolHealthy=False) to signal idle over-provisioning

A common pattern: set maxIdle to 2–3x minIdle to absorb burst traffic while keeping costs bounded.

yaml
pool:
    minIdle: 3
    maxIdle: 9   # burst headroom = 3x minIdle

Pool and Template Updates#

When you update a template spec, the warm pool is recycled:

Existing idle pods (running the old spec) are drained
New idle pods are created with the updated spec
Running sandboxes are not affected

During the transition, the pool may temporarily drop below minIdle. Plan updates during low-traffic windows if uninterrupted pool availability is critical.