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
pausedsandbox, it starts the resume and answers202once the resume is under way, after several seconds. - On a
runningsandbox, it answers200, and on astartingone202. - On every sandbox, it moves
expires_atto at least now plustimeout, never earlier.timeoutdefaults to 300 seconds, andnullleaves the expiry unchanged. The sandbox’stimeoutfield stays as created.
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
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>, withindexcounted from 1. Its tags are the source’s, with the request’s tags merged over them. - Swarm. The source and every sibling share one
swarmID 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
terminatedwithtermination_reasonno_capacity.
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.