Sandbox pools let you pre-warm containers so that new sandboxes start instantly without waiting for image pulls or container initialization.
Creating a Pool
from tensorlake.sandbox import SandboxClient
client = SandboxClient()
pool = client.create_pool(
image="python:3.11-slim",
cpus=1.0,
memory_mb=512,
ephemeral_disk_mb=1024,
warm_containers=3 # Keep 3 containers warm and ready
)
print(f"Pool ID: {pool.pool_id}")
Creating Sandboxes from a Pool
Pass the pool_id when creating a sandbox to use a pre-warmed container:
# Create sandbox from pool — starts instantly
sandbox = client.create(pool_id=pool.pool_id)
print(f"Sandbox ID: {sandbox.sandbox_id}")
Pool Configuration
| Parameter | Type | Default | Description |
|---|
image | str | Required | Container image to use |
cpus | float | 1.0 | CPUs per container |
memory_mb | int | 512 | Memory per container in MB |
ephemeral_disk_mb | int | 1024 | Disk per container in MB |
warm_containers | int | None | Number of containers to keep pre-warmed |
max_containers | int | None | Maximum total containers in the pool |
timeout_secs | int | 0 | Default timeout for sandboxes (0 = no timeout) |
secret_names | list[str] | [] | Secrets to inject into containers |
entrypoint | list[str] | None | Custom entrypoint command |
Managing Pools
List Pools
pools = client.list_pools()
for pool in pools:
print(f"{pool.pool_id}: {pool.image} ({pool.warm_containers} warm)")
Get Pool Details
pool_info = client.get_pool(pool.pool_id)
print(f"Image: {pool_info.image}")
print(f"Warm containers: {pool_info.warm_containers}")
print(f"Max containers: {pool_info.max_containers}")
Update Pool Configuration
updated_pool = client.update_pool(
pool_id=pool.pool_id,
image="python:3.11-slim",
warm_containers=5, # Increase warm containers
max_containers=20 # Set a ceiling
)
Delete a Pool
client.delete_pool(pool.pool_id)
A pool cannot be deleted while it has active sandboxes. Terminate all sandboxes in the pool first.
Scaling with Pools
Control how pools scale with warm_containers and max_containers:
pool = client.create_pool(
image="python:3.11-slim",
warm_containers=5, # Always keep 5 containers ready
max_containers=50 # Never exceed 50 total containers
)
warm_containers — containers that are pre-started and ready to be assigned as sandboxes. When a sandbox is created from the pool, a warm container is assigned immediately and a new one starts warming up to maintain the warm count.max_containers — the upper limit on total containers (warm + active sandboxes) in the pool.
Learn More
