> ## 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.

# Execs

An exec is a command run in a `running` sandbox, as its own process with its own output, stdin, and exit code. Execs are served by the data plane with a [token](https://developers.telnyx.com/docs/edge-compute/sandboxes/authentication.md#sandbox-token), never by the control plane.

## Running a Command

`POST /sandbox/{id}/exec` starts a command. The response is `201` with the exec in `starting` or `running`. The CLI's `exec` starts the command, streams its output, and exits with its exit code.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu exec doc-run-42 \
  --workdir /workspace \
  --env DATA_PATH=/workspace/data.csv \
  -- sh -c 'echo "$DATA_PATH $PWD"'
```

```bash API theme={null}
curl -X POST "$DATA_API/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": ["sh", "-c", "echo \"$DATA_PATH $PWD\""],
    "workdir": "/workspace",
    "env": { "DATA_PATH": "/workspace/data.csv" }
  }'
```

```text Output theme={null}
/workspace/data.csv /workspace
```

The CLI's exit status is the command's own.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu exec doc-run-42 \
  -- sh -c 'echo "cleaning 3 files"; exit 7'
echo $?
```

```text Output theme={null}
cleaning 3 files
7
```

| Field | Default | Description |
| - | - | - |
| `command` | Required | An array of 1 to 4,096 arguments of at most 131,071 bytes each, in a request body of at most 1 MiB. No shell is implied. Use `["bash", "-lc", "..."]` for shell syntax. |
| `env` | None | Variables merged over the sandbox's environment, for this exec only. Rules as on the create. |
| `workdir` | The sandbox's `workdir`, else the image's `WORKDIR`, else `/` | An absolute path. |
| `timeout` | None | Seconds before the exec is ended. |
| `user` | `root` | A user name or a numeric UID that exists in the image. An unknown user is refused with `422 unknown_user`. |
| `pty` | None | Runs the command in a terminal. See [PTY](#pty). |

Any number of execs run at once in one sandbox.

A command that cannot start, such as a binary that is not on the image's `PATH` or a `workdir` that does not exist, is refused with `400 bad_request` and the error's text. No exec is created. A request body over 1 MiB is refused with `413 request_too_large`.

## Exec Object

```json Output theme={null}
{
  "data": {
    "id": "exec-0193c4e8-2c1d-7a4b-9e0f-6d8a2b4c6e10",
    "sandbox_id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d",
    "command": ["sh", "-c", "echo \"$DATA_PATH $PWD\""],
    "workdir": "/workspace",
    "timeout": 600,
    "user": null,
    "pty": null,
    "status": "exited",
    "exit_code": 0,
    "reason": null,
    "created_at": "2026-11-11T19:20:02Z",
    "finished_at": "2026-11-11T19:20:41Z"
  }
}
```

| `status` | Meaning |
| - | - |
| `starting`, `running` | The process is starting or running. |
| `exited` | The process exited. `exit_code` is its code, or `-1` when a signal ended it. |
| `failed` | The platform failed to run the process. `reason` is `agent_error`. |
| `terminated` | The exec was ended by its `timeout` or by the sandbox's termination. `reason` is `timeout` or `sandbox_terminated`. |
| `interrupted` | The sandbox paused while the exec ran. The process continues in the sandbox, but this exec record no longer streams it. |

## Output

`GET /sandbox/{id}/exec/{exec_id}/attach` upgrades to a WebSocket. The upgrade request carries the token in `Authorization`. `offset` starts the stream at a byte offset, and `0` replays from the beginning.

```bash API theme={null}
WS_API=${DATA_API/https/wss}
websocat -H "Authorization: Bearer $SANDBOX_TOKEN" \
  "$WS_API/$SANDBOX_ID/exec/$EXEC_ID/attach?offset=0"
```

Every message is a JSON text frame. Data is base64.

```json Output theme={null}
{"type":"output","stream":"stdout","data":"Q29sbGVjdGluZyBwYW5kYXMK","offset":0}
{"type":"output","stream":"stderr","data":"V0FSTklORzogLi4uCg==","offset":20}
{"type":"heartbeat"}
{"type":"exit","status":"exited","exit_code":0,"reason":null}
```

### Server Messages

| `type` | Fields | Meaning |
| - | - | - |
| `output` | `stream`, `data`, `offset` | Bytes from `stdout` or `stderr`. One offset counts both streams. |
| `truncated` | `oldest_offset` | The requested offset is older than the guest still holds. The stream continues from `oldest_offset`. |
| `heartbeat` | None | Sent every 30 seconds. An open attach counts as activity. |
| `exit` | `status`, `exit_code`, `reason` | The exec ended. The server closes with code `1000`. |
| `stdin_closed` | None | A stdin write was refused because stdin is closed. |
| `error` | `error` | The server closes with `1008` for a client error or `1011` for a server error. |

### Client Messages

| `type` | Fields | Meaning |
| - | - | - |
| `stdin` | `data` | Bytes for the exec's stdin, base64, at most 64 KiB decoded. |
| `stdin_eof` | None | End-of-file on stdin. |
| `resize` | `rows`, `cols` | A new terminal size, for a [PTY](#pty) exec. |

A message over 128 KiB closes the socket with `1009`, and an unknown type with `1008`. Disconnecting never ends the exec and never closes its stdin. A client reattaches with the last offset it received plus the length of that data.

An error before the upgrade, such as `404` or `409 sandbox_paused`, is a plain HTTP response.

`GET /sandbox/{id}/exec/{exec_id}?wait=10` waits up to 10 seconds for the exec to finish before returning it, for clients that only need the exit code.

The guest keeps the last 8 MiB of each exec's output, for the 32 most recently finished execs. Output records stay readable until the sandbox terminates.

## Stdin

Stdin is written over the exec's [attach WebSocket](#output). `POST /sandbox/{id}/exec/{exec_id}/stdin/close` sends end-of-file, and answers `202` with the exec, also once the exec has ended. Closing an attach never closes stdin and never ends the exec. A `stdin` message after stdin is closed receives `stdin_closed`.

## Signals

`POST /sandbox/{id}/exec/{exec_id}/kill` sends a signal to the exec's process group. The response is `202` with the exec as it was before the signal, also once the exec has ended.

```json Request theme={null}
{ "signal": "SIGTERM" }
```

`signal` is one of `SIGTERM`, `SIGKILL` (default), `SIGINT`, `SIGHUP`, `SIGQUIT`, `SIGUSR1`, and `SIGUSR2`. Another name is refused with `400`.

## PTY

A PTY exec runs a command in a terminal, for shells, editors, REPLs, and programs that behave differently without one. It is an ordinary exec with a `pty` object.

The request below starts a login shell in a terminal of 40 rows and 120 columns.

```json Request theme={null}
{
  "command": ["bash", "-l"],
  "pty": { "rows": 40, "cols": 120, "term": "xterm-256color" }
}
```

| Field | Description |
| - | - |
| `pty.rows`, `pty.cols` | The terminal size, each 1 to 65,535. |
| `pty.term` | The `TERM` value, at most 64 bytes. Default `xterm-256color`. |

A PTY merges stdout and stderr into one stream, as a terminal does. Its output arrives as `output` messages with `stream` `stdout`.

The exec's [attach WebSocket](#output) carries keystrokes and screen output.

* **Input.** Each keystroke or pasted block is a `stdin` message, base64.
* **Output.** Screen output, including escape sequences, arrives as `output` messages.
* **Resize.** A `resize` message changes the terminal size.

```json Client Messages theme={null}
{"type":"stdin","data":"bHMgLWxhCg=="}
{"type":"resize","rows":50,"cols":160}
```

A `resize` on an exec without `pty` is refused. Disconnecting leaves the shell running, and a new attach resumes from any offset the guest still holds.

The shell ends when its process exits, for example after `exit` is written to stdin. A [kill](#signals) with `SIGHUP` ends it as a closed terminal would.

## List

`GET /sandbox/{id}/exec` lists the sandbox's execs, newest first, 20 per page and at most 100. `status` filters, and repeats.

## Execs and Pauses

Execs keep their records across a pause. After a resume, finished execs show their output and exit codes. An exec that was running at the pause reads `interrupted`. Its process keeps running in the sandbox, and a kill or a stdin close on the `interrupted` record answers `202` with the record. An attach that is open when the sandbox pauses keeps receiving heartbeats and is not told. A new attach after the resume receives `exit` with status `interrupted`.

Exec requests to a paused sandbox are refused with `409 sandbox_paused`. Send `connect` first.
