Skip to main content
A sandbox is composed from independent parts on its create request. Sandboxes also compose with each other, as the state of one becomes the source of the next.

Parts

Each part is set by its own field on the create request, or by the matching flag of telnyx-edge sandbox-cpu create, and a part left out takes its default. The request below composes a 2 vCPU sandbox from the official Python image. It reaches only PyPI and OpenAI, and sends an OpenAI key that the sandbox never holds. It pauses after 5 idle minutes and terminates after an hour.
Request

Source

A create names exactly one source.

Size

A size outside these values is refused with 422 resources_not_allowed. A sandbox from a template or a snapshot takes its source’s sizes.

Main Command

command is optional, and its presence changes how the sandbox ends.
  • Without command, the sandbox idles and serves execs until it times out or is terminated.
  • With command, the command is the sandbox’s main process. It runs once, when the sandbox first reaches running. Its exit terminates the sandbox with termination_reason exited and its exit_code. Its output is the sandbox’s logs, and its stdin is reached through GET /sandbox/{id}/attach.
Request
See Linux for the user and directory the main command runs with.

Environment

An invalid variable is refused with 422 invalid_env. See Linux for the order in which variables apply, and Limits for their sizes.

Network

network sets the outbound policy, the secret rules, and access to ports.

Lifetime

timeout, on_timeout, idle_timeout, and on_idle set when the sandbox pauses or terminates on its own. See Platform-Managed Lifecycle.

Name, Tags, and Region

Lineage

Each arrow below is a request that turns one sandbox’s source into the next.
  • Image to template. An image is booted once, its server started, and its ready state kept as a template.
  • Template to sandbox. A sandbox from a template resumes that ready state, with the server already listening.
  • Sandbox to snapshot. A snapshot keeps a running sandbox’s memory and disks, and new sandboxes start from it.
  • Sandbox to forks. A fork copies a running sandbox into as many as 20 sandboxes at once, within the organization’s sandbox quota, each with its live state.