Skip to main content
Sandboxes are built to be created, forked, and discarded in large numbers. Each sandbox is sized when it is created, and a quota in each region bounds how many an organization runs at once.

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 with 422 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 timeout terminates or pauses a sandbox that runs too long.
  • An idle_timeout pauses 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 an Idempotency-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.