Skip to main content
A sandbox moves between four states. Requests pause, resume, and terminate it, an agent connects to it at the start of each turn, and a fork copies a running sandbox into many.

States

A sandbox is always in one of four states. Each arrow below is a request or an event that moves it to the next. started_at is set when the boot starts. The sandbox reads running with ready true about 2 seconds later, and the started lifecycle event marks that moment.

Pause and Resume

POST /sandbox/{id}/pause pauses a running sandbox. The response is 202. The sandbox reads running until the pause completes, then paused, with paused_at and a pause_reason of customer, idle_timeout, or timeout. See Persistence for what a pause keeps. POST /sandbox/{id}/resume restores a paused sandbox on the same host. The response is 202, and the sandbox reads starting, then running. A resume when the organization is at its quota is refused with 429 quota_exceeded, and the sandbox stays paused. Execs and file requests to a paused sandbox are refused with 409 sandbox_paused. telnyx-edge sandbox-cpu pause and resume send the same requests and wait for the state.

Connect

POST /sandbox/{id}/connect is the request an agent sends at the start of each turn.
Request
  • On a paused sandbox, it starts the resume and answers 202 once the resume is under way, after several seconds.
  • On a running sandbox, it answers 200, and on a starting one 202.
  • On every sandbox, it moves expires_at to at least now plus timeout, never earlier. timeout defaults to 300 seconds, and null leaves the expiry unchanged. The sandbox’s timeout field stays as created.
A connect counts as activity for idle_timeout.

Terminate

POST /sandbox/{id}/terminate ends a sandbox in any state and discards its memory, disks, and snapshots. The response is 202, and the sandbox reads terminated once the host has released it. A second terminate answers 202 with the sandbox unchanged. telnyx-edge sandbox-cpu terminate sends it after a confirmation, which --yes skips. A terminated sandbox’s termination_reason says why it ended.

Wait

GET /sandbox/{id}/wait?timeout=10 returns once the sandbox is paused or terminated, or after timeout seconds, at most 10. timeout=0 answers at once, and a larger value is capped at 10. A client uses it to wait for a pause or a terminate to complete.

Fork

POST /sandbox/{id}/fork creates up to 20 siblings of a running sandbox, each with its memory, processes, and disks as they are now.
Request
The response is 202 at once, with every sibling in starting.
Output
  • Live state. Each sibling starts from the source’s state at the moment of the fork. The source’s processes stand still while that state is saved, about 10 seconds at 1 GiB, with its state reading running, and continue afterwards.
  • Names and tags. A sibling’s name is <name>-<index>, with index counted from 1. Its tags are the source’s, with the request’s tags merged over them.
  • Swarm. The source and every sibling share one swarm ID for their whole lives, and a fork of a sibling joins the same swarm. GET /sandbox?swarm=<id> lists them.
  • Placement. A sibling no host can place reads terminated with termination_reason no_capacity.
A fork of a sandbox that is not running is refused with 409 sandbox_not_running. A fork past the quota is refused whole with 429 quota_exceeded. The source holds a slot of the quota, so the largest fork under the default quota of 20 is 19 siblings.