Images
Every sandbox and template starts from an OCI image.- Reference.
image.refis an OCI image reference that names its registry, such asdocker.io/library/python:3.12-slim,ghcr.io/acme/agent:1.4, or a digest. A reference without a registry host, such aspython:3.12-slim, is refused with422 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
ENTRYPOINTandCMDare never run. The image’sUSER,ENV, andWORKDIRare the defaults.
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
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
--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.- The platform builds the image and boots it.
start_commandstarts as the template’s main process, withworkdirandenv.ready_commandruns about 8 seconds after the start command, then every second until it exits0, for up toready_timeoutseconds.- The platform freezes the template’s processes and checkpoints the template’s memory and disks.
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
running with the start command’s process already serving. The create above took about 3 seconds.
Workstation
Output
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, anddisk_gibare the template’s. Any of them besidetemplateis refused with422 template_field_conflict.network,timeout,on_timeout,idle_timeout,on_idle,name,tags,secrets_env,secrets_files, andregionapply per sandbox.- An unknown or deleted template is refused with
422 unknown_template. A template notreadyis refused with409 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.