Skip to main content
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.

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 runs and lists execs, in a 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 writes the main command’s stdin and returns its exit code.
      • /stdin/close closes the main command’s stdin.
      • /logs returns the main command’s logs.
      • /files reads, writes, lists, and deletes files.
        • /rename renames a file or directory.
      • /metrics returns the sandbox’s resource usage.
      • /lifecycle_event lists the sandbox’s lifecycle events.
    • /lifecycle_event lists every sandbox’s lifecycle events.
Port traffic 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.