Skip to main content
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.
These examples require a Sandbox-enabled account and a telnyx-edge release containing the sandbox-cpu commands.
The canonical Sandbox OpenAPI contract 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.

Prerequisites

  • The telnyx-edge CLI. See Installation.
  • A Telnyx API key, stored for the CLI and in TELNYX_API_KEY for the API. See Create API Keys.
  • curl and jq for the API requests.
Workstation

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

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.
API
The token is valid for one hour in every region. See Authentication.

3. Write a File

Write a script into the workspace disk.
Workstation

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.
Read the file the script wrote. With -, the CLI writes the file to stdout, and -q drops its summary line.
The exec’s output also streams over its attach WebSocket. See Execs.

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.
Request the file from the internet on the port’s URL.
Shell
Anyone with this URL reaches the port. See Ports 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.
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.
Once the sandbox is running again, the HTTP server is still serving. It resumed from where it paused, without a restart.
Shell

7. Terminate

Terminate the sandbox. The CLI asks for a confirmation, which --yes skips.
The sandbox’s memory, disks, and snapshots are discarded.

Next Steps

  • Templates start a sandbox with its server already running.
  • Fork copies a running sandbox into many.
  • Network Limits restrict where a sandbox connects.
  • Secrets give a sandbox credentials it never sees.