Skip to main content
Every sandbox is a Linux virtual machine booted from an OCI image, never a container that shares the host’s kernel. The image provides the userland. The platform provides the kernel, the first process, and the disks.

Control Plane Support

A Linux sandbox supports every operation of the common control plane, through the API or the telnyx-edge CLI.

Virtual Machine

A disk that fills returns ENOSPC to the writing process. The sandbox keeps running.

Image Requirements

  • Platform. The image must offer linux/amd64. From a multi-platform index, the linux/amd64 manifest is used.
  • Layers. Layers are gzip-compressed or plain tar. zstd and foreign layers are refused.
  • Size. The unpacked image must fit the 8 GiB root disk.
  • Registry. The reference names its registry host. See Templates.
The build drops extended attributes, so file capabilities set in the image are lost. Device nodes and FIFOs in the image are not created.

Processes and Users

The image’s ENTRYPOINT and CMD are never run. Root in a sandbox is root in its virtual machine only.

Environment Variables

Each process receives its environment in layers. A later layer replaces an earlier variable of the same name.
  1. The platform defaults: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin, HOME=/root, LANG=C.UTF-8, and the certificate variables listed under Secrets, which point common clients at /etc/ssl/certs/ca-certificates.crt.
  2. The image’s ENV.
  3. The create’s env.
  4. Secrets delivered by secrets_env.
  5. An exec’s own env, for that exec.
The certificate variables are set with or without secret rules.

Reserved

Identity

The sandbox’s /etc/machine-id is written at its first boot. A sandbox created from a template, a snapshot, or a fork receives a new machine ID, new SSH host keys, and a reseeded random number generator before its code resumes.