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

# Creation

A sandbox is created with one request through the control plane. The request names the sandbox's source and sets its other parts, and a batch creates many sandboxes of one definition at once.

`POST /sandbox` creates a sandbox. The create names one source and sets the rest of the sandbox's parts, each described in [Composition](https://developers.telnyx.com/docs/edge-compute/sandboxes/composition.md#parts). The response is `201` with the sandbox in `starting`.

The request below creates a 2 vCPU sandbox from the official Python image. The CLI waits until the sandbox is `running` and prints its ID.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu create \
  --image docker.io/library/python:3.12-slim \
  --name doc-run-42 \
  --tag task=data-cleanup \
  --cpu 2 \
  --memory 2048 \
  --timeout 1800 \
  --idle-timeout 300 \
  --env PYTHONUNBUFFERED=1
```

```bash API theme={null}
curl -X POST https://api.telnyx.com/v2/compute/sandbox \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-run-42" \
  -d '{
    "image": { "ref": "docker.io/library/python:3.12-slim" },
    "name": "doc-run-42",
    "tags": { "task": "data-cleanup" },
    "cpu": 2,
    "memory_mib": 2048,
    "timeout": 1800,
    "idle_timeout": 300,
    "env": { "PYTHONUNBUFFERED": "1" }
  }'
```

```text Output theme={null}
Waiting for sandbox sb-us-east-2-01a1d715-ca93-760b-a01b-20d1b9ee4865 to be running...
sb-us-east-2-01a1d715-ca93-760b-a01b-20d1b9ee4865
```

## Batch Create

`POST /sandbox/batch` creates up to 10 sandboxes of one definition. The body is a create body with a `count`. `from` is allowed.

```json Request theme={null}
{
  "count": 3,
  "template": "web-agent",
  "name": "grader",
  "timeout": 900
}
```

The response is `200` with one entry per item, and the totals.

```json Output theme={null}
{
  "items": [
    {
      "index": 1,
      "sandbox": {
        "id": "sb-us-east-1-...",
        "name": "grader-1",
        "state": "starting",
        ...
      }
    },
    {
      "index": 2,
      "sandbox": {
        "id": "sb-us-east-1-...",
        "name": "grader-2",
        "state": "starting",
        ...
      }
    },
    {
      "index": 3,
      "error": { "code": "90019", "title": "no_capacity", ... }
    }
  ],
  "created": 2,
  "failed": 1
}
```

`index` counts the items from 1, and item `i` of a named batch is `<name>-<i>`.

A batch past the quota is refused whole with `429 quota_exceeded`. A batch no host admits is refused with `503 no_capacity`.
