Sandbox Pool

A Sandbox Pool maintains a number of running (and ready) sandboxes created from a Template. When a developer creates a new sandbox from that template, one of the ready sandboxes in the pool is picked and handed off immediately, making it available for use without waiting for setup procedures.

Ready Sandboxes

A sandbox pool has a configuration parameter min which defines the minimum number of ready sandboxes to maintain in the pool. When the actual count of ready sandboxes falls below this number, the pool automatically creates more sandboxes to meet the requirement.

If sandboxes fail during the setup procedure (due to a script error or any other cause), the pool marks those sandboxes as errored. They will be removed automatically if the total number of sandboxes in the pool exceeds max, which is optional and defaults to the value of min.

Standby

When a new sandbox in a Sandbox Pool reaches Ready state, it is placed in Standby: all running processes are stopped and jobs are disabled. Everything is restarted when the sandbox is claimed by a new owner, and no in-memory state is carried over.

Readiness Probes

The Sandbox Pool relies on the Ready state of the sandbox to determine whether it is eligible to be claimed. A failing readiness probe can prevent the sandbox from reaching Ready state and will exclude it from being claimed.

If a custom readiness probe should not run while the sandbox is in the pool, add the following check before the probe command:

[[ -z "$SANDBOX_POOL_ID" ]] || exit 0
...probe logic

Daemons

Similarly, if a daemon should not run while the sandbox is in the pool, add the same check above.

Auto Scaling

The min configuration parameter can have different values for different time windows. This allows org admins to accurately control the pool size according to actual usage patterns, effectively reducing costs during off-peak hours.

Claiming a Sandbox

When a sandbox pool is enabled and has ready sandboxes available, creating a new sandbox from the same template automatically matches the pool and picks a ready sandbox. The system falls back to regular sandbox creation if no matching pool is found or there are no ready sandboxes.

A user can also explicitly claim a sandbox from a pool. This is especially useful when debugging failures in a pooled sandbox — the user can claim the problematic sandbox directly for inspection.