Skip to main content
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 for the image requirements and the environment the image runs in.

Private Registries

image.registry_secret names a secret whose value is the registry credential, in the form user:token. The platform reads it when a build starts and never returns it.
Request
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.
Output
The build above took 106 seconds. The CLI’s --start-command and --ready-command each take one string, which runs as sh -c '<string>'. 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

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.
Output
The sandbox reaches running with the start command’s process already serving. The create above took about 3 seconds.
Workstation
Output
That process is the sandbox’s main command. Its exit ends the sandbox, and its output is the sandbox’s 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

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.