Sandbox Scaling
A sandbox’s size is set at create and fixed for its life. A sandbox created from a template or a snapshot takes that source’s size, because the size is part of the saved memory. A create that names a size beside a template is refused with422 template_field_conflict. See Composition for the allowed sizes.
Fleet Scaling
A fleet is many independent sandboxes, typically one per user, task, or agent run.
A fork answers at once with every sibling in
starting, then places each sibling as soon as the source’s state is saved. The siblings share a swarm ID with their source, and a list request filters by it.
Placement depends on available capacity and access to the saved state.
Warm pools of started sandboxes Preview will hand out a template’s sandboxes without a boot or a restore.
Workload Concurrency
A sandbox can run multiple execs concurrently, subject to its execution limits. Each exec is its own process with its own output stream, stdin, and exit code. A long task runs as one exec while the agent sends other execs beside it. See Execs.Capacity
A paused or terminated sandbox does not count against the concurrency quota. A create, batch, or fork past the quota is refused whole with
429 quota_exceeded. When no host has room, a create is refused with 503 no_capacity and a Retry-After header. A batch item no host admits is an error entry in the batch response. A fork sibling no host can place reads terminated with termination_reason no_capacity. See Beta Limitations for the values.
Reclaiming Capacity
- A
timeoutterminates or pauses a sandbox that runs too long. - An
idle_timeoutpauses or terminates a sandbox no client is using. - A paused sandbox frees its quota and keeps its state.
Operating at Scale
Every create and lifecycle request accepts anIdempotency-Key header. A retried request with the same key receives the first response and creates nothing new. Lifecycle Events reports every state change across all sandboxes from one cursor.