> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

Agent Sandboxes has two planes. The **control plane** manages sandboxes. It creates them, changes their state, and terminates them, in every region from one endpoint. The **data plane** is where a sandbox is used. It runs commands, moves files, streams output, and carries traffic to ports, in the sandbox's own region.

The control plane acts **on** a sandbox. The data plane acts **in** one.

## Control Plane

The control plane is the Telnyx API at `https://api.telnyx.com`. It is one endpoint for every region, and the only one that requires a Telnyx API key. It stops at the edge of a sandbox and never reaches inside one, so it answers `404` for a data-plane request.

The control plane serves these resources.

* [`/v2/compute/sandbox`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/creation) lists and creates sandboxes.
  * [`/batch`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/creation#batch-create) creates many sandboxes at once.
  * [`/{sandbox_id}`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/operations#read) reads a sandbox and sets its tags.
    * [`/wait`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#wait) waits for a pause or a terminate.
    * [`/connect`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#connect) resumes the sandbox and extends its lifetime.
    * [`/pause`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#pause-and-resume), [`/resume`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#pause-and-resume), and [`/terminate`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#terminate) move it between its states.
    * [`/timeout`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle#timeout) sets its lifetime.
    * [`/fork`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) copies it into many sandboxes.
    * [`/snapshot`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/snapshots) takes and lists snapshots.
      * `/{snapshot_id}` reads and deletes a snapshot.
    * [`/network`](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/network-limits) changes its outbound policy.
  * [`/template`](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates) lists and creates templates.
    * `/{template_id}` reads and deletes a template.
      * `/rebuild` rebuilds it.
  * [`/token`](https://developers.telnyx.com/docs/edge-compute/sandboxes/authentication#sandbox-token) issues a token.
* [`/v2/compute/secrets`](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets) holds the organization's secrets.

## Data Plane

Each region has its own data plane at `https://api.<region>.sandbox.telnyxcompute.com`. It requires a token, never an API key. It stops at the edge of its region, serves only that region's sandboxes, and issues no tokens.

The data plane serves these resources for its own region.

* `/v2/compute/sandbox`
  * `/{sandbox_id}`
    * [`/exec`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/execs) runs and lists execs, in a [PTY](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/execs.md#pty) when asked.
      * `/{exec_id}` reads an exec.
        * `/attach` streams its output and writes its stdin.
        * `/kill` signals it.
        * `/stdin/close` closes its stdin.
    * [`/attach`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/main-command#attach) writes the main command's stdin and returns its exit code.
    * [`/stdin/close`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/main-command#stdin) closes the main command's stdin.
    * [`/logs`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/main-command#logs) returns the main command's logs.
    * [`/files`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/files) reads, writes, lists, and deletes files.
      * `/rename` renames a file or directory.
    * [`/metrics`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/metrics) returns the sandbox's resource usage.
    * [`/lifecycle_event`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) lists the sandbox's lifecycle events.
  * [`/lifecycle_event`](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) lists every sandbox's lifecycle events.

[Port traffic](https://developers.telnyx.com/docs/edge-compute/sandboxes/out-of-band-access/ports.md) reaches a port in a sandbox at `https://<sandbox_id>-<port>.<region>.sandbox.telnyxcompute.com`, for HTTP and WebSocket requests. Ports are public by default.

The line between acting **on** a sandbox and acting **in** it has two exceptions, both on the data plane.

* **Management at the region.** The data plane also accepts management requests for its own region, at the same paths as the control plane, so a client that holds a token can pause or resume a sandbox without the control plane.
* **Records of a sandbox.** Lifecycle events and metrics describe a sandbox from the outside, yet are read from the data plane, not the control plane, because each region keeps the record of its own sandboxes.

A region's data plane keeps serving clients that hold a valid token in the event of a control plane outage.
