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

# Templates

A template is a named image that the platform boots once, starts, and checkpoints when it is ready. A sandbox created from the template resumes that checkpoint, with the template's server already listening, instead of booting.

## Images

Every sandbox and template starts from an OCI image.

* **Reference.** `image.ref` is an OCI image reference that names its registry, such as `docker.io/library/python:3.12-slim`, `ghcr.io/acme/agent:1.4`, or a digest. A reference without a registry host, such as `python:3.12-slim`, is refused with `422 registry_not_allowed`.
* **Builds.** The first sandbox or template that names a reference builds it for the organization. The build resolves the reference to a digest and pins it. Later creates reuse the build.
* **Init.** A Telnyx init process runs as the first process. The image's `ENTRYPOINT` and `CMD` are never run. The image's `USER`, `ENV`, and `WORKDIR` are the defaults.

See [Linux](https://developers.telnyx.com/docs/edge-compute/sandboxes/linux.md) for the image requirements and the environment the image runs in.

### Private Registries

`image.registry_secret` names a [secret](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets.md) whose value is the registry credential, in the form `user:token`. The platform reads it when a build starts and never returns it.

```json Request theme={null}
{
  "image": {
    "ref": "ghcr.io/acme/agent:1.4",
    "registry_secret": "GHCR_PULL"
  }
}
```

A failed pull sets the template's `failure` to `image_pull_failed`, and a sandbox created from an image that cannot be pulled reads `terminated` with `termination_reason` `build_failed`. Nothing from the registry's response is returned.

## Creating a Template

`POST /v2/compute/sandbox/template` creates a template and builds it. The response is `202` with the template in `building`. The CLI's `--wait` waits until the template is `ready` or `failed`, and prints its ID.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu template create --name doc-web \
  --image docker.io/library/python:3.12 \
  --start-command 'python3 -m http.server 8000' \
  --ready-command 'curl -fsS http://127.0.0.1:8000' \
  --ready-timeout 60 \
  --wait
```

```json API theme={null}
{
  "name": "doc-web",
  "image": { "ref": "docker.io/library/python:3.12" },
  "start_command": ["python3", "-m", "http.server", "8000"],
  "ready_command": ["curl", "-fsS", "http://127.0.0.1:8000"],
  "ready_timeout": 60
}
```

```text Output theme={null}
Waiting for template tpl-us-east-2-01a1d753-25ef-74c5-9261-fcd1214236a3 to be ready...
tpl-us-east-2-01a1d753-25ef-74c5-9261-fcd1214236a3
```

The build above took 106 seconds. The CLI's `--start-command` and `--ready-command` each take one string, which runs as `sh -c '<string>'`.

| Field | Description |
| - | - |
| `name` | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`, not starting with `tpl-`. Unique per organization and region. |
| `image` | `ref` and an optional `registry_secret`, as on a sandbox create. |
| `start_command` | Optional. The template's main process, as an array of strings. |
| `ready_command` | Optional. A command run every second until it exits `0`. |
| `ready_timeout` | Seconds to wait for `ready_command`. Default `60`, maximum `600`. A value outside 1 to 600, or one without a `ready_command`, is refused with `400`. |
| `workdir`, `env` | The start command's working directory and environment. `env` cannot hold secret markers. |
| `cpu`, `memory_mib`, `disk_gib` | The size of every sandbox created from the template. Defaults as on a sandbox create. |
| `region` | The template's region. See [Regions](https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/regions.md). |

A name beginning with `tpl-` is refused with `400`, and a name already in use with `409 name_conflict`. An `env` value with a secret marker is refused with `422 template_env_secret`, because the environment is saved in the checkpoint's memory. Secrets go on each sandbox's create instead.

### Ready State

The build runs in four steps.

1. The platform builds the image and boots it.
2. `start_command` starts as the template's main process, with `workdir` and `env`.
3. `ready_command` runs about 8 seconds after the start command, then every second until it exits `0`, for up to `ready_timeout` seconds.
4. The platform freezes the template's processes and checkpoints the template's memory and disks.

Without a `start_command`, the checkpoint is taken as soon as the sandbox is up. Without a `ready_command`, it is taken one second after the start command starts.

### States

| `state` | Meaning |
| - | - |
| `building` | The image or the checkpoint is being built. |
| `ready` | Sandboxes can be created from the template. |
| `failed` | The build failed. `failure` names the cause. |

| `failure` | Cause |
| - | - |
| `image_pull_failed` | The image could not be pulled. |
| `build_failed` | The image could not be built into a root disk. |
| `start_failed` | `start_command` exited. |
| `ready_timeout` | `ready_command` did not exit `0` within `ready_timeout`. |
| `internal_error` | The platform failed. |

A `ready_command` that never passes costs the full build before the template reads `failed` with `failure` `ready_timeout`.

## Creating a Sandbox from a Template

`template` takes the template's ID or name, in place of `image`.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu create --template doc-web \
  --name doc-from-template \
  --timeout 600
```

```json API theme={null}
{
  "template": "doc-web",
  "name": "doc-from-template",
  "timeout": 600
}
```

```text Output theme={null}
Waiting for sandbox sb-us-east-2-01a1d754-c491-74da-9048-33efc8804ca8 to be running...
sb-us-east-2-01a1d754-c491-74da-9048-33efc8804ca8
```

The sandbox reaches `running` with the start command's process already serving. The create above took about 3 seconds.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu exec doc-from-template \
  -- curl -sS -o /dev/null -w '%{http_code}\n' \
  http://127.0.0.1:8000
```

```text Output theme={null}
200
```

That process is the sandbox's main [`command`](https://developers.telnyx.com/docs/edge-compute/sandboxes/composition#main-command). Its exit ends the sandbox, and its output is the sandbox's [logs](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/main-command.md#logs). Each sandbox receives a new machine identity and new entropy when it resumes.

* `command`, `workdir`, `env`, `image`, `cpu`, `memory_mib`, and `disk_gib` are the template's. Any of them beside `template` is refused with `422 template_field_conflict`.
* `network`, `timeout`, `on_timeout`, `idle_timeout`, `on_idle`, `name`, `tags`, `secrets_env`, `secrets_files`, and `region` apply per sandbox.
* An unknown or deleted template is refused with `422 unknown_template`. A template not `ready` is refused with `409 template_not_ready`.

## Managing Templates

| Request | Effect |
| - | - |
| `GET /sandbox/template` | Lists templates, filtered by `name`. The control plane lists every region's, and a region's data plane lists its own. |
| `GET /sandbox/template/{id}` | Returns one template. |
| `POST /sandbox/template/{id}/rebuild` | Pulls the image again, picking up a moved tag, and takes a new checkpoint. Returns the template to `building`. |
| `DELETE /sandbox/template/{id}` | Deletes the template. Returns `204`. |

A region's data plane also serves these requests for its own templates. `telnyx-edge sandbox-cpu template list`, `get`, `rebuild`, and `delete` send the same requests.

**Rebuild.** Sandboxes already created keep running on the previous build. A create sent during the rebuild is refused with `409 template_not_ready`. A create accepted before the rebuild, whose sandbox has not started yet, starts on the new build. A rebuild while `building` is refused with `409 operation_in_progress`.

**Delete.** The name is free at once and no new sandbox may name the template. Sandboxes created from it keep running.

**Tags** Preview. A tag such as `doc-web:v2` will pin a create to one build, while a rebuild moves the untagged name.

**Platform updates.** A checkpoint loads only on the platform build that took it. When the platform updates its hosts, it rebuilds affected templates automatically. The template reads `building` meanwhile.
