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:

1. The manager first tries to claim a ready idle pod (claimIdlePod)
2. If successful (hot claim), the pod is relabeled to active and returned immediately; pool replenishment happens asynchronously via ReplicaSet reconcile
3. If no idle pod exists (cold claim), the manager directly creates a new active pod (createNewPod); the warm pool remains reconciled to minIdle and does not expand for the burst

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

In practice, “available” means the pod is ready for claiming, not merely Pod Running. Template-declared Volume portals are pre-mounted in idle pods. A claim can bind any subset of those paths to Sandbox Volumes without bypassing the warm pool; declared paths omitted from the claim remain writable rootfs-backed directories and are captured by rootfs checkpoints.

Pool Fields#

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

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

Readiness Gates Pool Capacity#

Warm-pool capacity is counted from idle pods that are ready for claiming.

• An idle pod in Running phase but with Ready=False does not count toward idleCount
• A hot claim only selects idle pods that are already Ready
• Readiness is based on the sandbox container, procd, and volume portal state

Choosing minIdle:

maxIdle — Compatibility Ceiling#

maxIdle remains part of the template contract and must be greater than or equal to minIdle, but the current manager keeps warm-pool ReplicaSets at minIdle.

• It preserves compatibility for clients and future autoscaler behavior
• It works with template status conditions (PoolHealthy=False) to signal idle over-provisioning

For guaranteed burst capacity today, increase minIdle to the number of sandboxes you want pre-warmed.

yaml
pool:
    minIdle: 3
    maxIdle: 3

Pool and Template Updates#

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

1. Existing idle pods (running the old spec) are drained with per-node teardown and cluster replacement limits
2. New idle pods are created with the updated spec
3. Running sandboxes are not affected

Ready pods are additionally protected by an idle-pool PodDisruptionBudget and an availability floor. Unready pods do not consume that availability allowance, but they still consume their node's teardown budget. This allows independent nodes to clean up in parallel without sending an unbounded delete wave to one kubelet, container runtime, or CNI instance.

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

Next Steps#