> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scale

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.

| Dimension | What Scales | Mechanisms |
| - | - | - |
| Sandbox | The vCPU, memory, and disk of one sandbox | `cpu`, `memory_mib`, and `disk_gib` on the create, or a template's sizes |
| Fleet | The number of sandboxes | Batch creates, templates, snapshots, and fork |
| Workload | Processes inside one sandbox | Concurrent execs |

## 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](https://developers.telnyx.com/docs/edge-compute/sandboxes/composition.md#size) for the allowed sizes.

## Fleet Scaling

A fleet is many independent sandboxes, typically one per user, task, or agent run.

| Mechanism | Starting State | Use |
| - | - | - |
| [Batch create](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/creation.md#batch-create) | A fresh boot of an image, or a template's ready state | Many sandboxes of the same definition in one request |
| [Template](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates.md) | The image booted, its start command run, and its ready check passed | A server or tool already listening when the sandbox reaches `running` |
| [Snapshot](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/snapshots.md) | A running sandbox's memory and disk at the moment of the snapshot | Many sandboxes from a prepared state while its source sandbox exists |
| [Fork](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle.md#fork) | A running sandbox's memory and disk, now | Branching an agent's work into many attempts at once |

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](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/execs.md).

## Capacity

| Control | What It Limits | Scope |
| - | - | - |
| Concurrency quota | Sandboxes that are `starting` or `running` | Organization, per region |
| Per-sandbox sizes | vCPU, memory, and disk of one sandbox | Sandbox |
| Snapshot cap | Named snapshots held by one sandbox | Sandbox |
| Template cap | Templates held by one organization | Organization, per region |

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](https://developers.telnyx.com/docs/edge-compute/sandboxes/beta-limitations.md) 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](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events.md) reports every state change across all sandboxes from one cursor.
