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

# Quick Start

This guide creates a sandbox, writes and runs a Python script in it, serves an HTTP port from it, pauses and resumes it, and terminates it, with the `telnyx-edge` CLI and with the API.

> [!NOTE]
>
> These examples require a Sandbox-enabled account and a `telnyx-edge` release containing the `sandbox-cpu` commands.

The canonical [Sandbox OpenAPI contract](https://api.telnyx.com/v2/compute/sandbox/openapi.json) describes the supported API operations. The development CLI can fetch it with `telnyx-edge-dev sandbox-cpu openapi`, or send a request with `telnyx-edge-dev sandbox-cpu api METHOD /v2/compute/sandbox/...`. The CLI also has dedicated commands for every documented operation (the token mint is handled automatically), including `batch`, `fork`, `snapshot`, `template`, `network`, `logs`, `metrics`, `events`, and file management (`ls`, `stat`, `mkdir`, `mv`, `rm`). Check `sandbox-cpu --help` for the released commands and flags.

Lifecycle requests go to the control plane at `api.telnyx.com` with the API key. Execs and files go to the data plane in the sandbox's region with a token. The CLI sends both and handles the token itself. See [Architecture](https://developers.telnyx.com/docs/edge-compute/sandboxes/architecture.md).

## Prerequisites

* The `telnyx-edge` CLI. See [Installation](https://developers.telnyx.com/docs/edge-compute/reference/cli.md#installation).
* A Telnyx API key, stored for the CLI and in `TELNYX_API_KEY` for the API. See [Create API Keys](https://developers.telnyx.com/docs/development/api-fundamentals/create-api-keys.md).
* `curl` and `jq` for the API requests.

```bash Workstation theme={null}
telnyx-edge auth api-key set $TELNYX_API_KEY
```

## 1. Create a Sandbox

Create a sandbox from the official Python image, with a 30-minute lifetime. The CLI waits until the sandbox is `running` and prints its ID.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu create \
  --image docker.io/library/python:3.12-slim \
  --name doc-quick-start \
  --timeout 1800
```

```bash API theme={null}
export CONTROL_API=https://api.telnyx.com/v2/compute/sandbox
CREATE_RESPONSE=$(curl --fail-with-body -sS -X POST "$CONTROL_API" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": { "ref": "docker.io/library/python:3.12-slim" },
    "name": "doc-quick-start",
    "timeout": 1800
  }') || { echo "Sandbox create failed" >&2; exit 1; }
export SANDBOX_ID=$(echo "$CREATE_RESPONSE" | jq -er '.data.id') || exit 1
echo "$SANDBOX_ID"
```

The ID names the sandbox's region. Sandbox IDs, region selection, and startup times vary. The first sandbox from an image also builds the image, which takes longer than later creates.

With the API, the sandbox may initially be `starting`. Poll until it is `running` before proceeding.

```bash API theme={null}
while :; do
  STATUS_RESPONSE=$(curl --fail-with-body -sS "$CONTROL_API/$SANDBOX_ID" \
    -H "Authorization: Bearer $TELNYX_API_KEY") || exit 1
  STATE=$(echo "$STATUS_RESPONSE" | jq -er '.data.state') || exit 1
  case "$STATE" in
    running)
      echo "$STATUS_RESPONSE" | jq '.data | {state, expires_at}'
      break
      ;;
    terminated|failed)
      echo "Sandbox entered $STATE before becoming ready" >&2
      exit 1
      ;;
    starting)
      sleep 2
      ;;
    *)
      echo "Unexpected sandbox state: $STATE" >&2
      exit 1
      ;;
  esac
done
```

## 2. Get a Token

With the API, request a token from the control plane, and keep it with the base URL of the data plane in the sandbox's region. The CLI mints and caches the token itself, so it has no step here.

```bash API theme={null}
RESPONSE=$(curl --fail-with-body -sS -X POST "$CONTROL_API/token" \
  -H "Authorization: Bearer $TELNYX_API_KEY") || exit 1
export SANDBOX_TOKEN=$(echo "$RESPONSE" | jq -er .data.token) || exit 1
export SANDBOX_REGION=$(echo "$SANDBOX_ID" | sed -E 's/^sb-(.*)-[0-9a-f]{8}-[0-9a-f-]{27}$/\1/')
export REGION_BASE=$(echo "$RESPONSE" | jq -r --arg region "$SANDBOX_REGION" '.data.regions[$region] // empty')
test -n "$REGION_BASE" || { echo "Sandbox region is not in the token response" >&2; exit 1; }
export DATA_API="$REGION_BASE/v2/compute/sandbox"
```

The token is valid for one hour in every region. See [Authentication](https://developers.telnyx.com/docs/edge-compute/sandboxes/authentication.md).

## 3. Write a File

Write a script into the workspace disk.

```bash Workstation theme={null}
cat > primes.py <<'EOF'
import json
primes = [n for n in range(2, 100)
          if all(n % d for d in range(2, int(n ** 0.5) + 1))]
result = {"count": len(primes), "largest": primes[-1]}
json.dump(result, open("/workspace/result.json", "w"))
print(f"found {len(primes)} primes")
EOF
```

```bash Workstation theme={null}
telnyx-edge sandbox-cpu cp primes.py \
  doc-quick-start:/workspace/primes.py
```

```bash API theme={null}
curl -s -X PUT \
  "$DATA_API/$SANDBOX_ID/files?path=/workspace/primes.py" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  --data-binary @primes.py | jq .data.size_bytes
```

## 4. Run It

Run the script as an exec. The CLI streams the script's output and exits with its exit code. With the API, start the exec, then wait up to 10 seconds for it to finish.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu exec doc-quick-start \
  -- python3 /workspace/primes.py
```

```bash API theme={null}
EXEC_ID=$(curl -s -X POST $DATA_API/$SANDBOX_ID/exec \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": ["python3", "/workspace/primes.py"]}' \
  | jq -r .data.id)

curl -s "$DATA_API/$SANDBOX_ID/exec/$EXEC_ID?wait=10" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  | jq '.data | {status, exit_code}'
```

Read the file the script wrote. With `-`, the CLI writes the file to stdout, and `-q` drops its summary line.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu cp -q \
  doc-quick-start:/workspace/result.json -
```

```bash API theme={null}
curl -s \
  "$DATA_API/$SANDBOX_ID/files?path=/workspace/result.json" \
  -H "Authorization: Bearer $SANDBOX_TOKEN"
```

The exec's output also streams over its attach WebSocket. See [Execs](https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/execs.md#output).

## 5. Serve a Port

Start an HTTP server on port 8000 as a second exec. It keeps running beside other execs. The CLI's `exec` streams until its command ends, so the server is started in the background inside the sandbox and the exec returns at once.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu exec doc-quick-start \
  --workdir /workspace \
  -- sh -c 'nohup python3 -m http.server 8000 >/dev/null 2>&1 &'
```

```bash API theme={null}
curl -s -X POST $DATA_API/$SANDBOX_ID/exec \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": ["python3", "-m", "http.server", "8000"],
    "workdir": "/workspace"
  }' | jq -r .data.status
```

Request the file from the internet on the port's URL.

```bash Shell theme={null}
curl --retry 10 --retry-delay 1 --retry-all-errors --fail-with-body -sS "https://$SANDBOX_ID-8000.$SANDBOX_REGION.sandbox.telnyxcompute.com/result.json"
```

Anyone with this URL reaches the port. See [Ports](https://developers.telnyx.com/docs/edge-compute/sandboxes/out-of-band-access/ports.md) to require a traffic token.

## 6. Pause and Resume

Pause the sandbox. Its memory, processes, and files are saved, and it stops using CPU. The CLI waits until the sandbox is `paused`.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu pause doc-quick-start
```

```bash API theme={null}
curl -s -X POST $CONTROL_API/$SANDBOX_ID/pause \
  -H "Authorization: Bearer $TELNYX_API_KEY" > /dev/null
curl -s "$CONTROL_API/$SANDBOX_ID/wait?timeout=10" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  | jq '.data | {state, remaining}'
```

Resume it. The CLI's `resume` waits until the sandbox runs again. With the API, `connect` resumes it and extends its lifetime, as an agent does at the start of each turn.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu resume doc-quick-start
```

```bash API theme={null}
curl -s -X POST $CONTROL_API/$SANDBOX_ID/connect \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 900}' | jq .data.state
```

Once the sandbox is `running` again, the HTTP server is still serving. It resumed from where it paused, without a restart.

```bash Shell theme={null}
curl -s https://$SANDBOX_ID-8000.$SANDBOX_REGION.sandbox.telnyxcompute.com/result.json
```

## 7. Terminate

Terminate the sandbox. The CLI asks for a confirmation, which `--yes` skips.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu terminate --yes doc-quick-start
```

```bash API theme={null}
curl -s -X POST $CONTROL_API/$SANDBOX_ID/terminate \
  -H "Authorization: Bearer $TELNYX_API_KEY" | jq .data.state
```

The sandbox's memory, disks, and snapshots are discarded.

## Next Steps

* [Templates](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates.md) start a sandbox with its server already running.
* [Fork](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle.md#fork) copies a running sandbox into many.
* [Network Limits](https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/network-limits.md) restrict where a sandbox connects.
* [Secrets](https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets.md) give a sandbox credentials it never sees.
