> ## 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.

# Composition

A sandbox is composed from independent parts on its create request. Sandboxes also compose with each other, as the state of one becomes the source of the next.

## Parts

Each part is set by its own field on the [create request](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/creation.md), or by the matching flag of `telnyx-edge sandbox-cpu create`, and a part left out takes its default.

The request below composes a 2 vCPU sandbox from the official Python image. It reaches only PyPI and OpenAI, and sends an OpenAI key that the sandbox never holds. It pauses after 5 idle minutes and terminates after an hour.

```json Request theme={null}
{
  "image": { "ref": "docker.io/library/python:3.12-slim" },
  "cpu": 2,
  "memory_mib": 2048,
  "env": { "PYTHONUNBUFFERED": "1" },
  "network": {
    "egress": "allowlist",
    "allow_out": ["pypi.org", "*.pythonhosted.org"],
    "rules": {
      "api.openai.com": {
        "headers": {
          "Authorization": "Bearer {{secrets.OPENAI_KEY}}"
        }
      }
    }
  },
  "timeout": 3600,
  "idle_timeout": 300,
  "name": "research-agent"
}
```

### Source

A create names exactly one source.

| Field | Starts From |
| - | - |
| `image` | A fresh boot of an OCI image. `{"ref": "...", "registry_secret": "..."}`. See [Templates](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates.md#images). |
| `template` | A template's ready state, by ID or name. See [Templates](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates.md#creating-a-sandbox-from-a-template). |
| `from` | A snapshot's memory and disks. `{"snapshot": "snap-..."}`. See [Snapshots](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/snapshots.md). |

### Size

| Field | Default | Allowed |
| - | - | - |
| `cpu` | `1` | `1` or `2` vCPU |
| `memory_mib` | `1024` | `256` to `4096` |
| `disk_gib` | `16` | `16`. The workspace disk, beside an 8 GiB root disk. |

A size outside these values is refused with `422 resources_not_allowed`. A sandbox from a template or a snapshot takes its source's sizes.

### Main Command

`command` is optional, and its presence changes how the sandbox ends.

* **Without `command`**, the sandbox idles and serves [execs](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/execs.md) until it times out or is terminated.
* **With `command`**, the command is the sandbox's main process. It runs once, when the sandbox first reaches `running`. Its exit terminates the sandbox with `termination_reason` `exited` and its `exit_code`. Its output is the sandbox's [logs](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/main-command.md#logs), and its stdin is reached through `GET /sandbox/{id}/attach`.

```json Request theme={null}
{
  "image": { "ref": "ghcr.io/acme/eval-runner:3" },
  "command": ["python", "-m", "evals.run", "--suite", "smoke"],
  "workdir": "/workspace"
}
```

See [Linux](https://developers.telnyx.com/docs/edge-compute/sandboxes/linux.md#processes-and-users) for the user and directory the main command runs with.

### Environment

| Field | Description |
| - | - |
| `env` | Variables for every process in the sandbox. Names match `[A-Za-z_][A-Za-z0-9_]*`. A `{{secrets.<NAME>}}` marker becomes a [placeholder](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets.md#placeholders). |
| `workdir` | An absolute path. The main command's working directory, and the default for execs. |
| `secrets_env`, `secrets_files` | Secret values delivered into the sandbox. See [Secrets](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets.md#delivery-into-the-sandbox). |

An invalid variable is refused with `422 invalid_env`. See [Linux](https://developers.telnyx.com/docs/edge-compute/sandboxes/linux.md#environment-variables) for the order in which variables apply, and [Limits](https://developers.telnyx.com/docs/edge-compute/sandboxes/platform/limits.md) for their sizes.

### Network

`network` sets the outbound policy, the secret rules, and access to ports.

| Field | Description |
| - | - |
| `network.egress` | `public` (default), `allowlist`, or `blocked`. See [Network Limits](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/network-limits.md). |
| `network.allow_out` | CIDRs and domains reachable under `allowlist`. |
| `network.rules` | Headers the host adds to HTTPS requests. See [Secrets](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets.md#secret-rules). |
| `network.public_traffic` | `true` (default) or `false`. See [Ports](https://developers.telnyx.com/docs/edge-compute/sandboxes/out-of-band-access/ports.md#access). |

### Lifetime

`timeout`, `on_timeout`, `idle_timeout`, and `on_idle` set when the sandbox pauses or terminates on its own. See [Platform-Managed Lifecycle](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle.md).

### Name, Tags, and Region

| Field | Description |
| - | - |
| `name` | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`. Unique among the organization's sandboxes that are not terminated, or the create is refused with `409 name_conflict`. |
| `tags` | Up to 20 key-value pairs. Keys are 1 to 63 characters and values at most 255. |
| `region` | The sandbox's region. See [Regions](https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/regions.md). |

## Lineage

Each arrow below is a request that turns one sandbox's source into the next.

The diagram shows an OCI image built into a template or creating a sandbox directly, a template creating a sandbox, a running sandbox snapshotted with the snapshot creating new sandboxes, and a running sandbox forked into as many as 20 sandboxes.

* **Image to template.** An image is booted once, its server started, and its ready state kept as a [template](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates.md).
* **Template to sandbox.** A sandbox from a template resumes that ready state, with the server already listening.
* **Sandbox to snapshot.** A [snapshot](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/snapshots.md) keeps a running sandbox's memory and disks, and new sandboxes start from it.
* **Sandbox to forks.** A [fork](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle.md#fork) copies a running sandbox into as many as 20 sandboxes at once, within the organization's sandbox quota, each with its live state.
