Telnyx Compute — Full Documentation

Edge compute functions, runtime bindings, stateful actors, and private networking. Complete page content for the Compute section of the Telnyx developer docs (https://developers.telnyx.com). Root index: https://developers.telnyx.com/llms.txt · Lightweight index for this section: https://developers.telnyx.com/development/llms/compute-llms-txt.md

Overview

Edge Compute

Source: https://developers.telnyx.com/docs/edge-compute/platform-overview.md

Edge Compute is the platform of compute primitives you use to build and deploy applications to the Telnyx edge — serverless functions, stateful actors, KV, object storage, and SQL (coming soon). It’s particularly powerful when combined with two other sets of Telnyx primitives to create AI agents that act in the physical world:

AI — inference, embedding, RAG, memory (coming soon), text-to-speech, speech-to-text, and voice design
Real-world communication — calling, messaging, and email (coming soon)

Start building

Functions quickstart — install the CLI, scaffold, ship, and curl a live URL
Call the Telnyx API — reach calling, messaging, and AI from a function, no keys in your code
Stateful Actors quick start — durable per-entity state and coordination
KV quick start — create a namespace, bind it, read and write
Pricing and Limits

Functions

Source: https://developers.telnyx.com/docs/edge-compute/overview.md

A function is the compute primitive of Telnyx Edge Compute: an ordinary HTTP server, packaged as a container, deployed to Telnyx’s global edge network, and served at its own public URL. You write a server that listens on PORT; one command builds and ships it.

index.ts

import * as http from "node:http";

const server = http.createServer((req, res) => {
  if (req.url === "/health") { res.writeHead(200); res.end(); return; }
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ message: "Hello from Telnyx Edge Compute!" }));
});

server.listen(process.env.PORT || 8080);

telnyx-edge ship
# 📡 Your function is live at:
#    https://demo-myorg.telnyxcompute.com

On its own, a function just echoes HTTP. What makes it useful is the platform it plugs into — key-value storage, durable per-entity state, object storage, the Telnyx API, and private networking — each declared as a binding and reachable from your handler. This page maps that platform; the rest of these docs go deep on each piece. Install the CLI, scaffold a function, ship it, and curl the live URL — about five minutes. HTTP is the only trigger today — there are no cron triggers. For scheduled work, call the function’s URL from an external scheduler, such as a GitHub Actions cron job.

The platform around your functions

Declare a binding in func.toml and it surfaces on env at runtime in TypeScript, or as REST and injected environment variables in every other language. See Bindings for the mechanics — these are the products worth reaching for. State and storage Globally distributed key-value storage with server-side TTL — an env binding in TypeScript, REST everywhere else. For caches, sessions, and feature flags. Beta — durable per-entity state and coordination: one instance per name, one call at a time. For counters, per-user state, and anything that needs a serialized owner. S3-compatible buckets for files and media — a separate product, reached over its S3 API from any language. Connect to Telnyx A pre-authenticated client for Voice, Messaging, and AI — or plain REST with the injected key. Answer calls, send messages, and run inference without managing credentials.

Languages

telnyx-edge new-func -l scaffolds a project in TypeScript (ts), JavaScript (js), Go (go), Python (python), or Java (quarkus). Each language uses its own standard server contract — node:http, Go’s http.Handler, ASGI, Quarkus Funqy — documented in HTTP handler. The binding SDK (@telnyx/edge-runtime) — a typed env exposing a pre-authenticated Telnyx client, secrets, and KV namespaces — is TypeScript-only today. The other runtimes use the same features over REST and injected environment variables.

Where your code runs

Functions run on the infrastructure that carries Telnyx voice and messaging traffic: edge sites inside carrier facilities, close to end users rather than in generic cloud availability zones. Each region is backed by multiple independent sites across different providers, with automatic failover if a site goes down.

Resources

The entrypoint contract for each language. Environment variables, secrets, routing, and versions. Every telnyx-edge command and flag. Request timeouts, payload sizes, and quotas. Free tier plus usage-based rates for requests and CPU time. Ask questions and share what you build.

Quickstart

Source: https://developers.telnyx.com/docs/edge-compute/quickstart.md

Deploy your first function end-to-end: install the CLI, authenticate, scaffold, ship, and prove it with curl. A function is a container running your own HTTP server on Telnyx infrastructure, reachable at a public URL. The code steps below are shown for every supported language — pick a tab. TypeScript is the default and the only one with the typed binding SDK today; the rest are fully supported for plain HTTP.

Prerequisites

A Telnyx account — sign up if you don’t have one.
The toolchain for your language: Node.js ≥ 18 (TypeScript/JavaScript), Go, Python 3, or Java with Maven.

1. Install the CLI

The telnyx-edge CLI ships as binaries on the GitHub releases page. Assets are version-stamped, and each tarball extracts into a versioned directory containing the binary.

Linux (amd64)

curl -fsSL https://github.com/team-telnyx/edge-compute/releases/download/v0.2.3/telnyx-edge-v0.2.3-linux-amd64.tar.gz | tar xz
sudo mv telnyx-edge-v0.2.3-linux-amd64/telnyx-edge /usr/local/bin/

macOS (Apple silicon)

curl -fsSL https://github.com/team-telnyx/edge-compute/releases/download/v0.2.3/telnyx-edge-v0.2.3-macos-arm64.tar.gz | tar xz
sudo mv telnyx-edge-v0.2.3-macos-arm64/telnyx-edge /usr/local/bin/

For Intel Macs use the macos-amd64 asset; Windows zips are on the same releases page. Verify the install:

telnyx-edge --version

2. Authenticate

Authenticate before creating a function — new-func registers the function with the platform, which requires credentials.

# Interactive: opens your browser for OAuth
telnyx-edge auth login

# Or headless (CI, containers): set an API key directly
telnyx-edge auth api-key set

# Confirm
telnyx-edge auth status

Credentials persist to ~/.telnyx-edge/config.toml. The CLI does not read a TELNYX_API_KEY environment variable — in CI, run auth api-key set as a setup step.

3. Create a function

new-func creates the function server-side, writes the assigned UUID into func.toml, and scaffolds a working project. Pass -l to pick the language:

TypeScript

telnyx-edge new-func -l ts -n hello
cd hello
npm install

JavaScript

telnyx-edge new-func -l js -n hello
cd hello
npm install

telnyx-edge new-func -l go -n hello
cd hello

Python

telnyx-edge new-func -l python -n hello
cd hello

Java

telnyx-edge new-func -l quarkus -n hello
cd hello

Every scaffold contains a func.toml that ties the directory to the registered function:

[edge_compute]
func_id = "7819cf01-39a8-400e-9bce-3d792ffa4017"  # assigned by new-func
func_name = "hello"

The entrypoint file and its contract differ by language — TypeScript and JavaScript run their own server; Go, Python, and Java hand you a handler and run the server for you. Here is the scaffolded entrypoint, condensed to a health check plus a default JSON response:

index.ts

import * as http from "node:http";

const server = http.createServer((req, res) => {
  // Liveness/readiness probes — answer first
  if (req.url === "/health" || req.url?.startsWith("/health/")) {
    res.writeHead(200); res.end(); return;
  }
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ message: "Hello from Telnyx Edge Compute!" }));
});

server.listen(process.env.PORT || 8080);

index.js

import * as http from "node:http";

const server = http.createServer((req, res) => {
  // Liveness/readiness probes — answer first
  if (req.url === "/health" || req.url?.startsWith("/health/")) {
    res.writeHead(200); res.end(); return;
  }
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ message: "Hello from Telnyx Edge Compute!" }));
});

server.listen(process.env.PORT || 8080);

handler.go

package function

import (
  "encoding/json"
  "net/http"
)

// The platform runs the server and calls Handle per request.
func Handle(w http.ResponseWriter, r *http.Request) {
  w.Header().Set("Content-Type", "application/json")
  json.NewEncoder(w).Encode(map[string]string{
    "message": "Hello from Telnyx Edge Compute!",
  })
}

function/func.py

import json

def new():
    return Function()

class Function:
    async def handle(self, scope, receive, send):
        body = json.dumps({"message": "Hello from Telnyx Edge Compute!"}).encode()
        await send({"type": "http.response.start", "status": 200,
                    "headers": [[b"content-type", b"application/json"]]})
        await send({"type": "http.response.body", "body": body})

src/main/java/functions/Function.java

package functions;

import io.quarkus.funqy.Funq;

public class Function {
    @Funq
    public Output function(Input input) {
        return new Output("Hello from Telnyx Edge Compute!");
    }
}

These are trimmed for the quickstart. HTTP handler has the full scaffold for each language, the exact entrypoint contract, and how request bodies and health probes work.

4. Ship

telnyx-edge ship

ship uploads the project, builds it, deploys it, and monitors the rollout (default timeout 5 minutes; --timeout to change). The output ends with the live URL:

✅ Func 'hello' is now deployed!

📡 Your function is live at:
   https://hello-.telnyxcompute.com

💡 Test your function:
   curl https://hello-.telnyxcompute.com

Every function gets a URL of the form {func-name}-{org-nickname}.telnyxcompute.com — see Routes & Domains.

5. Call it

Use the URL ship printed. Every scaffold answers a GET with the same default response:

curl -sS https://hello-.telnyxcompute.com
# → {"message":"Hello from Telnyx Edge Compute!"}

Sending request bodies differs by contract — the TypeScript, JavaScript, Go, and Python scaffolds read the raw body, while the Java (Funqy) scaffold is JSON-in, JSON-out. See HTTP handler for each. The function is live. Iterate by editing the entrypoint and running telnyx-edge ship again — each successful ship creates an immutable revision you can roll back to.

Next Steps

Bindings — pre-authenticated Telnyx client, secrets, and KV on env.
KV quick start — persist data across requests from your function.

Best Practices

Source: https://developers.telnyx.com/docs/edge-compute/best-practices.md

An Edge Compute function is a real container running your own HTTP server — not a per-request sandbox. Most of the practices below follow from that model: module scope runs once per container, an escaped exception kills a process, and state has to live somewhere other than the container. Code samples are TypeScript. The same principles apply in every runtime; the binding SDK (@telnyx/edge-runtime) is TypeScript-only today, so other languages use environment variables and the REST APIs where a binding is shown.

Configuration

Keep Secrets Out of Code

Store credentials as secrets — the CLI takes the key and value as positional arguments:

telnyx-edge secrets add API_KEY "sk-..."

Every secret is injected into your functions as a plain environment variable, so this works in any language:

const apiKey = process.env.API_KEY;

TypeScript projects that declare a [[secrets]] binding in func.toml can also read it through env.SECRETS.get(""), which telnyx-edge types type-checks against the declared handles. Both surfaces are live at the same time — see Secrets.

Budget for the Platform Timeout

The request timeout is 30 seconds by default and 60 seconds at most — there is no func.toml field that raises it. A request that exceeds it is terminated with a 504. Set your own deadlines on outbound calls a few seconds below the platform’s so you fail with a useful error instead (see Time Out and Retry Outbound Calls), and split work that genuinely needs longer. Exact numbers: Limits.

Name Functions for Their URL

The function name becomes the hostname — {func-name}-{org-nickname}.telnyxcompute.com — and new-func registers the function with the platform at scaffold time, so pick the name up front:

# Good — the URL says what it serves
telnyx-edge new-func -l ts -n user-api

# Bad — you'll be curling https://test-yourorg.telnyxcompute.com in production
telnyx-edge new-func -l ts -n test

Performance

Initialize Once, at Module Scope

A container serves many requests. Module scope runs once per container; the request callback runs per request. Build clients, load config, and compile anything expensive outside the callback:

import * as http from "node:http";

// Once per container — reused across requests
const client = new SomeApiClient({ timeout: 5000 });

const server = http.createServer(async (req, res) => {
  // Per request — keep construction out of here
  const data = await client.get("/data");
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify(data));
});

server.listen(process.env.PORT || 8080);

The same rule holds everywhere: package-level variables in Go, module-level objects in Python.

Keep Cold Starts Small

A new container starts when traffic scales up or after a deploy, and the first request it serves waits for everything before server.listen — imports, client construction, config loads. Keep dependencies minimal, and lazy-load heavy libraries used only on rare paths so the common path doesn’t pay for them.

Cache Expensive Reads in KV

Declare a KV namespace in func.toml and it resolves as a binding on env:

# func.toml
[storage.kv.CACHE]
id = "550e8400-e29b-41d4-a716-446655440000"  # from `telnyx-edge storage kv create`

import { env } from "@telnyx/edge-runtime";

async function getUser(userId: string) {
  const cached = await env.CACHE.get(`user/${userId}`, { type: "json" });
  if (cached) return cached;

  const user = await fetchUserFromDb(userId);
  await env.CACHE.put(`user/${userId}`, JSON.stringify(user), { expirationTtl: 300 }); // seconds
  return user;
}

Two contracts to know:

expirationTtl is server-side expiry in whole seconds (≥ 1) and requires @telnyx/edge-runtime ≥ 0.2.2 — earlier versions accept the option and silently ignore it.
Keys allow a-z A-Z 0-9 - _ / = . and forbid colons — write user/123, not user:123.

Put State Where It Belongs

Containers come and go, and concurrent requests can land on different containers — anything kept in process memory is a cache at best. Pick the store by the shape of the data:

Data	Use	Why
Per-entity state, counters, coordination	Stateful Actors	One instance per name, one call at a time — read-modify-write without races
Caches, config, feature flags	KV	Small values (≤ 1 MiB), fast reads, last-write-wins
Files and large blobs	Storage buckets	S3-compatible object storage

Don’t build counters, locks, or rate limiters on KV: it has no transactions or compare-and-swap, and concurrent writers to one key are last-write-wins. That job is exactly what Stateful Actors exist for. Full comparison: Where state lives.

Reliability

Make Handlers Idempotent

Clients retry and webhooks are redelivered, so design handlers where processing the same request twice has the same effect as once. Key side effects on a caller-supplied identifier — a webhook event id, an Idempotency-Key header — and skip work already done. If the duplicate check itself must be race-free, do it inside a Stateful Actor; a check-then-act on KV can race.

Keep the Health Endpoint Fast

The scaffolds answer /health before any other routing:

if (req.url === "/health" || req.url?.startsWith("/health/")) {
  res.writeHead(200);
  res.end();
  return;
}

Keep that property: return immediately and never call a dependency from it, so a slow upstream can’t make your function look down.

Catch Everything at the Top of the Handler

Your function is one process. An exception that escapes the request callback — including an unhandled promise rejection — crashes it, drops every in-flight request, and makes the next request pay a cold start. Wrap the whole handler body:

const server = http.createServer(async (req, res) => {
  try {
    // ... handle the request
  } catch (err) {
    console.error("request failed:", err);
    res.writeHead(500, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "internal error" }));
  }
});

Time Out and Retry Outbound Calls

Don’t let a slow upstream ride you into the platform’s 30-second 504 — set an explicit deadline on every outbound call:

const response = await fetch("https://api.example.com/data", {
  signal: AbortSignal.timeout(5000),
});

Retry only network failures and 5xx responses, with exponential backoff, and keep the total budget under the platform timeout:

async function fetchWithRetry(url: string, attempts = 3): Promise {
  for (let i = 0; ; i++) {
    try {
      const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
      if (res.status < 500) return res; // success or client error — don't retry 4xx
      if (i === attempts - 1) return res;
    } catch (err) {
      if (i === attempts - 1) throw err;
    }
    await new Promise((r) => setTimeout(r, 2 ** i * 100)); // 100 ms, 200 ms, 400 ms
  }
}

Security

Validate input before use — check required fields and types, reject with 400. Nothing between the internet and your handler does it for you.
HTTPS only for outbound calls.
Never log secret values — and don’t log full request bodies, which may carry PII. Log metadata: method, path, status, duration.
Authenticate anything that mutates state — your function URL is public. Require a token or shared secret (stored as a secret, checked in the handler) before acting on a request.

Observability

There is no logs command and no metrics dashboard today. What you have is the output of ship, status, and inspect — plus whatever your function emits itself. So emit deliberately:

Send structured events over HTTP to a sink you control (a log aggregator, your own collector) if you need request-level visibility. There is no surface that shows you console.log output.
Propagate a request id — read X-Request-ID or generate one, return it in the response, and attach it to every event you emit, so a user-reported failure is findable in your sink.

Patterns and sink examples: Observability.

Next Steps

Limits — the exact numbers behind timeouts, memory, and payload sizes
Observability — building your own telemetry with no platform logging surface
Execution Model — container lifecycle, scaling, and cold starts

AI Assistants and Edge Compute

Source: https://developers.telnyx.com/docs/edge-compute/guides/ai-assistant-backend.md

Telnyx AI Assistants can call out to your own backend in several scenarios — resolving dynamic variables at the start of a conversation, executing webhook tool calls mid-conversation, and more. Whenever you need a backend for these callbacks, Telnyx Edge Compute is a natural fit: no server to manage, secrets injected at runtime, and deployment via a single CLI command. This guide walks through building a single Go function that handles both dynamic variables and webhook tool calls, using the demo app telnyx-ai-edge as the reference implementation.

What you’ll build

A support assistant for “Telnyx Logistics” that:

Greets callers by name (dynamic variables resolved from the caller’s phone number)
Has a lookup-order tool the assistant can call to retrieve order status, carrier, and estimated delivery

Both the dynamic variable lookup and the tool call hit one Edge Compute function at a single URL.

Prerequisites

A Telnyx account with Edge Compute enabled.
The telnyx-edge CLI installed and authenticated.
An existing AI Assistant (or you can create one via API as shown below).
Go 1.24+ installed locally (if following along with the Go sample).

Key concepts

Single function, two callbacks

Edge Compute routes all HTTP methods and paths under your function URL to your handler — path handling is up to your code (see Routes & Domains). The platform handles /health/liveness and /health/readiness probes automatically. In this guide, both the dynamic variables webhook and the webhook tool call point to the same function URL, so the handler dispatches on the request body shape rather than the URL path:

Dynamic variables webhook — Telnyx wraps the payload under data.event_type.
Webhook tool call — the body is the flat arguments object from the tool’s body_parameters schema (e.g. {"order_id": "ORD-10042"}).

You could also use separate paths (e.g. /dynamic-variables and /tool/lookup-order) if you prefer path-based routing — both approaches work. This guide uses body-shape dispatch to keep everything at a single URL.

Webhook signature verification

Telnyx signs every dynamic-variables webhook and webhook tool call with an Ed25519 key. The signature is in the telnyx-signature-ed25519 header, and the timestamp is in telnyx-timestamp. The signed message is "{timestamp}|{raw_body}". You must verify this signature to confirm the request is genuinely from Telnyx. Your org’s public key is available at:

GET https://api.telnyx.com/v2/public_key
Authorization: Bearer

The response contains data.public (not data.public_key) — the base64-encoded Ed25519 public key.

Dynamic variables response format

The response must nest variables under a dynamic_variables key. A flat object (e.g. {"customer_name": "James"}) is silently ignored — variables will remain unresolved.

{
  "dynamic_variables": {
    "customer_name": "James Smith",
    "account_tier": "premium"
  }
}

Timeout

The default dynamic variables webhook timeout is 1,500 ms. Edge Compute functions may occasionally need more time on a cold start, so consider setting dynamic_variables_webhook_timeout_ms on the assistant to a higher value (up to 10,000 ms). A value of 8,000 ms is a reasonable choice for edge backends.

Step 1: Scaffold the function

telnyx-edge new-func -l go -n telnyx-ai-edge
cd telnyx-ai-edge

This creates a func.toml with the registered function ID and a Go handler scaffold. The Go module must be named function (package function, entrypoint Handle(w, r)). Other module names fail to build: “malformed module path: missing dot in first path element.” Use go 1.24 in go.mod.

Step 2: Store the public key as a secret

Fetch your org’s public key and store it as an encrypted secret. The public key endpoint requires authentication — use your Telnyx API key:

# Get the public key (requires authentication)
PUBLIC_KEY=$(curl -s -H "Authorization: Bearer $TELNYX_API_KEY" \
  https://api.telnyx.com/v2/public_key | jq -r '.data.public')

# Store it as a secret (encrypted, org-scoped, injected as env var at runtime)
telnyx-edge secrets add TELNYX_PUBLIC_KEY "$PUBLIC_KEY"

The function reads this secret from os.Getenv("TELNYX_PUBLIC_KEY") at startup. Secrets are never visible in secrets list — only the name is shown.

Step 3: Write the handler

The handler does three things:

Verifies the Telnyx Ed25519 signature on every request
Detects whether the request is a dynamic-variables webhook or a tool call
Returns the appropriate response

handler.go

package function

import (
  "crypto/ed25519"
  "encoding/base64"
  "encoding/json"
  "io"
  "log"
  "net/http"
  "os"
  "strconv"
  "time"
)

const maxSkew = 5 * time.Minute

var publicKey ed25519.PublicKey

func init() {
  raw := os.Getenv("TELNYX_PUBLIC_KEY")
  if raw == "" {
    log.Println("warning: TELNYX_PUBLIC_KEY is not set; all requests will be rejected")
    return
  }
  key, err := base64.StdEncoding.DecodeString(raw)
  if err != nil || len(key) != ed25519.PublicKeySize {
    log.Printf("warning: TELNYX_PUBLIC_KEY is invalid (len=%d, err=%v)", len(key), err)
    return
  }
  publicKey = ed25519.PublicKey(key)
}

func Handle(w http.ResponseWriter, r *http.Request) {
  // Health probes are handled by the platform — don't add custom health routes
  if r.Method != http.MethodPost {
    http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
    return
  }

  body, err := io.ReadAll(r.Body)
  if err != nil {
    http.Error(w, "cannot read body", http.StatusBadRequest)
    return
  }

  if !verifyTelnyxSignature(r.Header, body) {
    http.Error(w, "invalid signature", http.StatusForbidden)
    return
  }

  // Dispatch on body shape: DV webhook has "data.event_type",
  // tool call is a flat args object
  if isDynamicVariablesRequest(body) {
    handleDynamicVariables(w, body)
    return
  }
  handleLookupOrder(w, body)
}

func isDynamicVariablesRequest(body []byte) bool {
  var probe struct {
    Data *struct {
      EventType string `json:"event_type"`
    } `json:"data"`
  }
  if err := json.Unmarshal(body, &probe); err != nil {
    return false
  }
  return probe.Data != nil
}

func verifyTelnyxSignature(h http.Header, body []byte) bool {
  if publicKey == nil {
    return false
  }

  sig := h.Get("telnyx-signature-ed25519")
  ts := h.Get("telnyx-timestamp")
  if sig == "" || ts == "" {
    return false
  }

  t, err := strconv.ParseInt(ts, 10, 64)
  if err != nil {
    return false
  }
  age := time.Since(time.Unix(t, 0))
  if age < -maxSkew || age > maxSkew {
    return false
  }

  s, err := base64.StdEncoding.DecodeString(sig)
  if err != nil {
    return false
  }

  signed := append([]byte(ts+"|"), body...)
  return ed25519.Verify(publicKey, signed, s)
}

// --- Dynamic Variables ---

type dvRequest struct {
  Data struct {
    EventType string `json:"event_type"`
    Payload   struct {
      Channel       string `json:"telnyx_conversation_channel"`
      AgentTarget   string `json:"telnyx_agent_target"`
      EndUserTarget string `json:"telnyx_end_user_target"`
      CallControlID string `json:"call_control_id"`
      AssistantID   string `json:"assistant_id"`
    } `json:"payload"`
  } `json:"data"`
}

type dvResponse struct {
  DynamicVariables map[string]any `json:"dynamic_variables"`
}

func handleDynamicVariables(w http.ResponseWriter, body []byte) {
  var req dvRequest
  if err := json.Unmarshal(body, &req); err != nil {
    http.Error(w, "bad json", http.StatusBadRequest)
    return
  }

  caller := req.Data.Payload.EndUserTarget

  resp := dvResponse{
    DynamicVariables: map[string]any{
      "customer_name":  lookupCustomerName(caller),
      "account_tier":   "premium",
      "open_order_id":  "ORD-10042",
      "support_region": "US",
    },
  }

  writeJSON(w, resp)
}

func lookupCustomerName(caller string) string {
  known := map[string]string{
    "+13128675309": "James Smith",
    "+15551234567": "Rachel Thomas",
  }
  if name, ok := known[caller]; ok {
    return name
  }
  return "there"
}

// --- Webhook Tool: lookup-order ---

type toolRequest struct {
  OrderID string `json:"order_id"`
}

type toolResponse struct {
  OrderID        string `json:"order_id"`
  Status         string `json:"status"`
  EstimatedDeliv string `json:"estimated_delivery"`
  Carrier        string `json:"carrier"`
}

func handleLookupOrder(w http.ResponseWriter, body []byte) {
  var req toolRequest
  if err := json.Unmarshal(body, &req); err != nil {
    http.Error(w, "bad json", http.StatusBadRequest)
    return
  }

  resp := toolResponse{
    OrderID:        req.OrderID,
    Status:         "shipped",
    EstimatedDeliv: "2025-04-10",
    Carrier:        "Telnyx Logistics",
  }

  writeJSON(w, resp)
}

func writeJSON(w http.ResponseWriter, v any) {
  w.Header().Set("Content-Type", "application/json")
  json.NewEncoder(w).Encode(v)
}

Step 4: Ship the function

telnyx-edge ship

The ship process takes 2–3 minutes. After uploaded successfully, poll telnyx-edge list until the status shows deploy_ok. Don’t trust a CLI timeout as a failure — the function may still be building server-side.

telnyx-edge list
# FUNC ID                          FUNCTION NAME    STATUS      INVOKE URL
# 917210e7-...                     telnyx-ai-edge   deploy_ok  https://telnyx-ai-edge-.telnyxcompute.com

Save the invoke URL — you’ll point the assistant at it next.

Step 5: Configure the AI Assistant

Set the function URL as both the dynamic variables webhook URL and the webhook tool URL on the assistant.

Dynamic variables webhook

In the Portal or via the API:

Field	Value
`dynamic_variables_webhook_url`	`https://telnyx-ai-edge-.telnyxcompute.com/`
`dynamic_variables_webhook_timeout_ms`	`8000`

Consider setting the timeout to 8,000 ms to give the function room on cold starts. The default 1,500 ms may be tight for a cold function.

Template variables in the assistant

Use {{variable_name}} in the assistant’s instructions and greeting to reference the variables your function returns:

instructions: "You are a support agent for Telnyx Logistics. The caller is {{customer_name}} (tier: {{account_tier}}). They may have open order {{open_order_id}}."
greeting: "Hi {{customer_name}}, thanks for calling Telnyx Logistics. How can I help you today?"

Webhook tool

Add a webhook tool that points to the same function URL:

{
  "type": "webhook",
  "webhook": {
    "name": "lookup-order",
    "description": "Look up the current status of a customer order by its order id.",
    "url": "https://telnyx-ai-edge-.telnyxcompute.com/",
    "method": "POST",
    "body_parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order id to look up, e.g. ORD-10042."
        }
      },
      "required": ["order_id"]
    }
  }
}

When the LLM decides to call lookup-order, Telnyx sends a POST with the tool arguments as the flat body ({"order_id": "ORD-10042"}), signed with the same Ed25519 key. Your function detects the body shape, handles it as a tool call, and returns the result.

Step 6: Test end-to-end

Call the function directly (without a signature — it’ll return 403, confirming it’s live):

curl -X POST https://telnyx-ai-edge-.telnyxcompute.com/ \
  -H "Content-Type: application/json" \
  -d '{"order_id":"ORD-10042"}'
# → 403 invalid signature  ← expected, signature verification is working

Make a test call to the assistant from the Portal or via the API:

curl --request POST \
  --url https://api.telnyx.com/v2/texml/ai_calls/ \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "From": "+13128675309",
    "To": "+15551234567",
    "AIAssistantId": "assistant-"
  }'

Verify in the conversation transcript that:
- The greeting includes the resolved customer_name
- The assistant can call lookup-order and read back real order data

Tips and gotchas

Choosing body-shape vs path-based dispatch

Since Edge Compute routes all paths to your handler, you can use path-based routing (e.g. r.URL.Path == "/tool/lookup-order") or body-shape dispatch as shown in this guide. Both work. If you configure separate URLs for the DV webhook and the tool on the assistant, path-based routing is natural. If you point both at the same URL, body-shape dispatch is the way to go. For a path-based routing example, see the RESTful API example in the Edge Compute CLI repo.

Consider a higher webhook timeout

The default dynamic variables webhook timeout is 1,500 ms. Edge Compute functions may occasionally need a bit more time on a cold start, so consider setting dynamic_variables_webhook_timeout_ms to 8,000 ms to give the function room. The maximum is 10,000 ms.

Always verify signatures

Without signature verification, anyone who knows your function URL can inject fake dynamic variables or tool responses. The telnyx-signature-ed25519 and telnyx-timestamp headers are present on every request from Telnyx.

Ship takes a few minutes

A normal ship takes 2–3 minutes. The CLI’s build monitor has a 5-minute timeout, but the build continues server-side regardless. If the CLI reports a timeout, check telnyx-edge list for the actual status before retrying — the function may have deployed successfully.

Secrets require re-shipping

Adding or changing a secret (telnyx-edge secrets add) does not affect an already-deployed function. Run telnyx-edge ship again to pick up the new secret.

The `dynamic_variables` wrapper is mandatory

Returning a flat JSON object like {"customer_name": "James"} will be silently ignored. Variables must be nested under dynamic_variables:

{
  "dynamic_variables": {
    "customer_name": "James"
  }
}

Next steps

Dynamic Variables — full reference for the DV webhook payload and resolution precedence.
Webhook signing — how Telnyx signs webhooks and how to verify signatures.
Edge Compute quickstart — getting started with your first function.
Secrets — encrypted, org-scoped environment variables.
Bindings — pre-authenticated Telnyx API client for your function.

Local Development

Source: https://developers.telnyx.com/docs/edge-compute/development.md

An Edge Compute function is an ordinary program in a container, not code inside a proprietary runtime. The TypeScript and JavaScript scaffolds run their own HTTP server on $PORT (default 8080); the Python, Go, and Quarkus scaffolds export a handler and the server is run for you. Local development is therefore unremarkable: run the program, curl localhost:8080, iterate, then telnyx-edge ship. Everything below runs against the projects generated by telnyx-edge new-func (see the Quickstart); the Python and Go serve rows add a small local entry point shown in their tabs:

Language	Serve locally	Test
TypeScript	`npm run build && npm start`	`node --test`
JavaScript	`node index.js`	`node --test`
Python	`uvicorn app:app --port 8080 --interface asgi3 --lifespan off`	`pytest`
Go	`go run ./cmd/local` (scratch `main`)	`go test ./...`
Java (Quarkus)	`./mvnw quarkus:dev`	`./mvnw test`

Run and test, by language

The scaffold’s index.ts (or index.js) at the project root is a node:http server. Build (TypeScript only) and run it:

npm install
npm run build   # tsc → dist/index.js
npm start       # node dist/index.js — for JavaScript: node index.js
# → Server running on port 8080

npm run dev runs index.ts directly through ts-node with no build step. The server reads process.env.PORT and falls back to 8080. Exercise it with curl:

curl localhost:8080/
# → {"message":"Hello from Telnyx Edge Compute!"}

curl -X POST localhost:8080/ -H "Content-Type: application/json" -d '{"name":"test"}'
# → {"message":"Hello from Telnyx Edge Compute!","data":{"name":"test"}}

curl -s -o /dev/null -w "%{http_code}\n" localhost:8080/health
# → 200

The /health fast-path at the top of the scaffold answers the platform’s probes — keep it fast and dependency-free when you rework the server. The scaffold starts its server at module load and exports nothing, so there is nothing to import in a unit test. Keep request handling in exported functions the server delegates to, test those with node --test, and treat curl against the running server as your integration test. The scaffold is an ASGI application: function/func.py exposes a module-level new() factory, and the returned instance’s handle(scope, receive, send) method is the ASGI callable. Any ASGI server runs it — with uvicorn, add a local entry point:

# app.py — local entry point, not part of the function contract
from function import new

app = new().handle

pip install uvicorn
uvicorn app:app --port 8080 --interface asgi3 --lifespan off
# → Uvicorn running on http://127.0.0.1:8080

--interface asgi3 is required — handle is a bound method and uvicorn’s interface auto-detection misclassifies it, returning 500s without the flag. --lifespan off silences a harmless Invalid ASGI scope type: lifespan error at startup — the scaffold doesn’t implement the lifespan protocol uvicorn probes for by default. uvicorn also never calls the optional start(cfg)/stop() hooks; only the platform does. For tests, the scaffold’s pyproject.toml already declares pytest, pytest-asyncio, and httpx as dev dependencies, with asyncio_mode = "strict" — mark async tests explicitly. No server is needed: call handle directly with a hand-built scope.

pip install -e ".[dev]"

# tests/test_handle.py
import json

import pytest

from function import new

@pytest.mark.asyncio
async def test_get_returns_greeting():
    func = new()
    sent = []

    async def receive():
        return {"type": "http.request", "body": b""}

    async def send(message):
        sent.append(message)

    scope = {"type": "http", "method": "GET", "path": "/", "headers": []}
    await func.handle(scope, receive, send)

    assert sent[0]["type"] == "http.response.start"
    assert sent[0]["status"] == 200
    assert json.loads(sent[1]["body"])["message"] == "Hello from Telnyx Edge Compute!"

pytest
# → 1 passed

The scaffold exports Handle(w http.ResponseWriter, r *http.Request) from package function — there is no main(); the platform provides the server. net/http/httptest drives Handle without one:

// handler_test.go
package function

import (
  "net/http"
  "net/http/httptest"
  "strings"
  "testing"
)

func TestHandlePostEchoesJSON(t *testing.T) {
  req := httptest.NewRequest(http.MethodPost, "/", strings.NewReader(`{"name":"test"}`))
  rec := httptest.NewRecorder()

  Handle(rec, req)

  if rec.Code != http.StatusOK {
    t.Fatalf("expected 200, got %d", rec.Code)
  }
  if !strings.Contains(rec.Body.String(), `"name":"test"`) {
    t.Fatalf("body did not echo request: %s", rec.Body.String())
  }
}

go test ./...
# → ok    function  0.6s

For a curl-able local server, add a scratch main in its own package. The import path is function because that is the module path in the scaffold’s go.mod:

// cmd/local/main.go — local harness only
package main

import (
  "log"
  "net/http"

  "function"
)

func main() {
  http.HandleFunc("/", function.Handle)
  log.Println("listening on :8080")
  log.Fatal(http.ListenAndServe(":8080", nil))
}

go run ./cmd/local
curl localhost:8080/
# → {"message":"Hello from Telnyx Edge Compute!"}

The scaffold is a Quarkus Funqy project. Dev mode gives hot reload on source changes and a debugger on port 5005:

./mvnw quarkus:dev

curl localhost:8080/ -H "Content-Type: application/json" -d '{"message":"ping"}'
# → {"message":"ping"}

The test stack (quarkus-junit5, rest-assured) is already in the pom.xml:

./mvnw test

Testing

A standalone function needs no emulator: the platform runs your program in a container and sends it HTTP, which is exactly what your terminal just did — the language-standard tools above are the whole testing story. (Projects that add Stateful Actors run locally with telnyx-edge dev; see its docs.) The one structural habit worth adopting: keep transport separate from logic. Parse, validate, and compute in plain functions; let the server (or Handle, or handle) stay a thin adapter. That keeps unit tests fast and keeps the binding limitation below out of most of your test suite.

Framework servers

For TypeScript and JavaScript, the platform contract is a process that binds the port in $PORT (default 8080). Any HTTP server that does so runs in the container — Express, Fastify, Hono, or anything else — and the server you ran locally is the server that runs deployed. There are no framework-specific guides.

Bindings and secrets

The env binding surface — [telnyx] clients, env.SECRETS.get(), KV namespaces, actors — resolves only inside a deployed function. A standalone function has no local binding emulation — to exercise binding-backed code paths, ship to a scratch function and curl its live URL. (Stateful Actors projects are the exception: telnyx-edge dev runs their actor stack locally so env. calls resolve.) Plain environment variables are the exception. In production, secrets created with telnyx-edge secrets add are injected as environment variables into your functions, and declaring a [telnyx] binding injects TELNYX_API_KEY. Code that reads plain env vars therefore works locally by exporting the same names:

# Locally: your shell
export MY_API_KEY=test-value

# Deployed: injected as an environment variable
telnyx-edge secrets add MY_API_KEY

Use throwaway values locally and never commit real ones. See Secrets and Environment variables.

Deploy

When it works locally, ship it:

telnyx-edge ship
# → 📡 Your function is live at:
#      https://-.telnyxcompute.com

Each successful ship creates an immutable revision; telnyx-edge revisions list shows them and telnyx-edge rollback retargets traffic to an earlier one. See Deploy.

Next Steps

Deploy — ship, revisions, and rollback
HTTP handler — the exact entrypoint contract per language
Bindings — the env surface a deployed function gets
CLI reference — every telnyx-edge command

Configuration

Source: https://developers.telnyx.com/docs/edge-compute/configuration.md

Every Edge Compute project has a TOML manifest at its root. It is the one place a function is configured: it identifies what telnyx-edge ship deploys and declares the bindings the runtime resolves onto env. Everything below is a block in that file. There are two forms:

func.toml (classic) — a single function. Written by telnyx-edge new-func, which also registers the function server-side, so the UUID func_id is already filled in. Declares [env_vars], [telnyx], [[secrets]], [storage.kv.], and [storage.cloudstorage.].
telnyx.toml (umbrella) — a TypeScript project with a top-level main entry, bundled client-side on ship. Declares the same binding blocks plus [[actors]], which classic projects cannot.

telnyx-edge types reads either form and writes telnyx-env.d.ts, typing env. for each declaration. Configuration changes take effect on the next telnyx-edge ship — there is no live update; re-run telnyx-edge types after changing a binding declaration so telnyx-env.d.ts matches the manifest. The binding blocks — [telnyx], [[secrets]], [storage.kv.], [storage.cloudstorage.], and [[actors]] (umbrella only) — each resolve to a typed handle on env. This page documents their manifest keys; the bindings catalogue lists every binding at a glance — declaration and env surface — and each block below links to its full documentation.

func.toml

new-func writes the minimal manifest — and because it registers the function server-side at scaffold time, the UUID func_id is already in it:

[edge_compute]
func_id = "7819cf01-39a8-400e-9bce-3d792ffa4017"
func_name = "demo-ts"

# For environment variables and secrets:
# Use telnyx-edge secrets add
# Secrets are injected as environment variables into all your functions

A manifest using every available block:

[edge_compute]
func_id   = "7819cf01-39a8-400e-9bce-3d792ffa4017"  # written by new-func — the function ship deploys
func_name = "demo-ts"                                # → https://demo-ts-7819cf01-3.telnyxcompute.com (name + func_id prefix)

[env_vars]                     # plain string env vars, injected on each deploy
LOG_LEVEL   = "info"
MAX_RETRIES = "3"

[telnyx]                       # pre-authenticated Telnyx API client
binding = "MY_TELNYX"          # → env.MY_TELNYX (TS); also injects TELNYX_API_KEY

[[secrets]]                    # typed handle onto a stored secret
binding = "STRIPE_KEY"         # → env.SECRETS.get("STRIPE_KEY")
name    = "STRIPE_API_KEY"     # the key stored with `secrets add`

[storage.kv.MY_KV]             # KV namespace binding — block key is the handle
id = "550e8400-e29b-41d4-a716-446655440000"   # → env.MY_KV

[storage.cloudstorage.ASSETS]  # Cloud Storage bucket binding — block key is the handle
bucket_name = "my-assets"      # → env.ASSETS; an existing bucket
region      = "us-east-1"      # us-central-1 | us-east-1 | us-west-1 | eu-central-1

There is no language key (the runtime comes from the project files the scaffold creates), no build block, and no timeout key — the request timeout is a platform property (default 30 s, maximum 60 s; see Limits).

[edge_compute] — identity

Key	Value
`func_id`	The function’s UUID, written by `new-func` when it registers the function server-side. This — not the directory — is what `ship` deploys, so swapping `func.toml` files switches deploy targets (the CI/CD staging pattern relies on this).
`func_name`	The function name, and the first part of the invoke URL: `https://{func_name}-{func_id-prefix}.telnyxcompute.com` (the suffix is derived from `func_id`; `telnyx-edge ship` and `list` print the exact host). See Routes & Domains.

[env_vars] — environment variables

Free-form key-value pairs injected as process environment variables on each deploy. All values are strings; changes take effect on the next ship; values are plaintext in git — put credentials in secrets instead. Dive in: Environment Variables.

[[secrets]] — secret bindings

Key	Value
`binding`	The handle your code passes to `env.SECRETS.get()`.
`name`	The stored secret key, from `telnyx-edge secrets add` .

The binding is the typed TypeScript surface; independently of it, every secret is injected as an environment variable into all functions in your organization. Dive in: Secrets.

[telnyx] — Telnyx API binding

Key	Value
`binding`	The property on `env` — `env.` is a pre-authenticated Telnyx SDK client in TypeScript functions.

Declaring the block also injects a TELNYX_API_KEY environment variable into the container — this is how non-TypeScript runtimes call the Telnyx API over plain REST. Documented in Telnyx API binding.

[storage.kv.] — KV namespace binding

Key	Value
block key “	The handle — a name you choose. `env.` is a `KvNamespace` (get/put/delete/list).
`id`	The KV namespace UUID, from `telnyx-edge storage kv create`.

Multiple blocks are allowed — each becomes its own env property. telnyx-edge types generates KvNamespace types for these blocks since CLI v0.2.4. Documented in the KV quick start.

[storage.cloudstorage.] — Cloud Storage bucket binding

Key	Value
block key “	The handle — a name you choose. `env.` is a `CloudStorageBucket` (get/put/head/delete/list). TypeScript-only, via `@telnyx/edge-runtime` ≥ 0.3.0.
`bucket_name`	The name of an existing Cloud Storage bucket — the binding points at a bucket, it doesn’t create one.
`region`	The bucket’s region: `us-central-1`, `us-east-1`, `us-west-1`, or `eu-central-1`.

Multiple blocks are allowed — each becomes its own env property. The runtime injects the credential, so no access key or secret key appears in your code. Documented in Cloud Storage binding.

telnyx.toml

The umbrella manifest replaces [edge_compute] with top-level keys and adds [[actors]]. On ship, the module graph rooted at main is bundled into a single file with esbuild (TypeScript/JavaScript only) and the manifest ships with it.

name = "account-svc"           # function name
main = "src/index.ts"          # entry module — exports the fetch handler (and the actor class)
compatibility_date = "2026-05-01"

[[actors]]
binding = "ACCOUNT"            # the property on env — your handle
type    = "Account"            # the class to instantiate per name

[telnyx]                       # same binding blocks as func.toml
binding = "MY_TELNYX"

[[secrets]]
binding = "GREETING"
name    = "DEMO_GREETING"

Key	Value
`name`	Function name, used by the platform to register the function.
`main`	Entry module — the root of the client-side esbuild bundle.
`compatibility_date`	Runtime compatibility pin.
`[[actors]]`	Actor bindings — `binding` is the `env` property, `type` the class to instantiate per name. Ship-time constraints (identifier rules, uniqueness, the 32-character type cap) are specified in the Stateful Actors configuration reference.

The project shape — one module exporting both the actor class and a fetch handler — is covered in Project Structure. telnyx-edge new-func --actor scaffolds it. Documented in Stateful Actors — the configuration reference covers the [[actors]] block in full.

Configured outside the manifest

The manifest references resources that exist outside it by name or ID — you create each one separately, and the block only points at it:

Secret values — stored server-side with telnyx-edge secrets; [[secrets]] and the injected environment variables only reference the key. See Secrets.
KV namespaces — created with telnyx-edge storage kv create; [storage.kv.] only references the namespace id. See the KV quick start.
Cloud Storage buckets — created in the Mission Control portal or over the S3-compatible API; [storage.cloudstorage.] only references an existing bucket by bucket_name. See Cloud Storage binding.

Ship-time validation

Binding handles and [env_vars] names share one env namespace. ship (and types) enforce two hard rules and warn on a third:

Duplicate [[secrets]] handles are rejected — ship fails, because env.SECRETS.get("") would be ambiguous.
A binding (or actor) named SECRETS is rejected when a [[secrets]] block is declared — it conflicts with the env.SECRETS namespace.
A name collision between [env_vars] and a binding — including an [env_vars] entry named SECRETS — only warns. Both land on env, so one shadows the other and ship proceeds; rename one.

Bindings catalogue — every binding at a glance: declaration and env surface for Telnyx API, Secrets, KV, Object storage, and Actors
Environment variables — everything that lands in the container’s environment
Secrets — both access surfaces for [[secrets]]
Telnyx API binding — the [telnyx] block and the env. client
KV quick start — the [storage.kv.] block and KvNamespace
Cloud Storage binding — the [storage.cloudstorage.] block and CloudStorageBucket
Stateful Actors configuration — the [[actors]] block in full
CLI reference — new-func writes the manifest; ship and types read it

Environment Variables

Source: https://developers.telnyx.com/docs/edge-compute/configuration/environment-variables.md

Functions run as real containers, so configuration reaches your code as ordinary process environment variables — process.env, os.environ, os.Getenv, System.getenv. There is no separate configuration API to learn.

What’s in the environment

Variable	Where it comes from
`PORT`	Set by the platform. Your HTTP server must listen on it.
Every `[env_vars]` key	Declared in `func.toml`; injected verbatim on each deploy.
Every secret key	`telnyx-edge secrets add` injects the key into all functions in your organization. See Secrets.
`TELNYX_API_KEY`	Injected when the function declares a `[telnyx]` binding. This is how non-TypeScript runtimes call the Telnyx API.

Declaring variables

Define non-sensitive configuration under [env_vars] in func.toml:

[edge_compute]
func_id   = "7819cf01-39a8-400e-9bce-3d792ffa4017"
func_name = "demo-ts"

[env_vars]
LOG_LEVEL   = "info"
MAX_RETRIES = "3"
DEBUG       = "false"

Three behavioral contracts:

All values are strings. Parse numbers and booleans in your code.
Changes take effect on the next telnyx-edge ship — there is no live update.
Names share the env namespace with bindings. If an [env_vars] entry has the same name as a declared binding — or is named SECRETS while a [[secrets]] block is declared — ship warns that one shadows the other on env and still proceeds; rename one. (A binding named SECRETS, or a duplicate [[secrets]] handle, is a hard error.)

[env_vars] values are plaintext in func.toml and end up in version control. Put credentials in secrets instead.

Reading variables

const port = Number(process.env.PORT ?? 8080);         // set by the platform
const logLevel = process.env.LOG_LEVEL ?? "info";      // from [env_vars]
const maxRetries = Number(process.env.MAX_RETRIES ?? "3");
const debug = process.env.DEBUG === "true";

import os

log_level = os.environ.get("LOG_LEVEL", "info")
max_retries = int(os.environ.get("MAX_RETRIES", "3"))
debug = os.environ.get("DEBUG", "false").lower() == "true"

package function

import (
    "os"
    "strconv"
)

func loadConfig() (logLevel string, maxRetries int, debug bool) {
    logLevel = os.Getenv("LOG_LEVEL")
    if logLevel == "" {
        logLevel = "info"
    }
    maxRetries, _ = strconv.Atoi(os.Getenv("MAX_RETRIES"))
    debug, _ = strconv.ParseBool(os.Getenv("DEBUG"))
    return
}

String logLevel = System.getenv().getOrDefault("LOG_LEVEL", "info");
int maxRetries = Integer.parseInt(System.getenv().getOrDefault("MAX_RETRIES", "3"));
boolean debug = Boolean.parseBoolean(System.getenv("DEBUG"));

Environment variables vs secrets

	`[env_vars]`	Secrets
Stored	Plaintext in `func.toml`, committed to git	Server-side; the CLI never prints values
Scope	One function	Every function in the organization
Changed by	Editing `func.toml`, then `ship`	`telnyx-edge secrets add`, then `ship`
Use for	Log levels, feature flags, public URLs, tuning knobs	API keys, passwords, signing keys

Next Steps

Secrets — the server-side counterpart for sensitive values, including the typed env.SECRETS surface for TypeScript
Bindings — typed, pre-authenticated handles instead of raw variables
Configuration — the full manifest reference: every func.toml and telnyx.toml key

Secrets

Source: https://developers.telnyx.com/docs/edge-compute/configuration/secrets.md

Secrets are key-value pairs for sensitive data — API keys, database passwords, signing keys. They are scoped to your organization, stored server-side, and never displayed by the CLI after you set them. Every function receives them; there are two ways to read one.

Managing secrets

The secrets commands take positional arguments:

# Add a secret — or update it, same command
telnyx-edge secrets add STRIPE_API_KEY "sk_live_abc123"
# ✓ Secret 'STRIPE_API_KEY' added successfully

# List secret keys (values are never shown)
telnyx-edge secrets list
# SECRET ID                              SECRET NAME         CREATED AT            UPDATED AT
# ------------                           ----------------    -----------------     -----------------
# 1f4cafea-21ce-4e2b-9740-17d971c3d892   DATABASE_PASSWORD   Jun 12, 2026, 09:41   Jun 12, 2026, 09:41
# 21ef7449-edbb-4248-b869-3d1352563a64   STRIPE_API_KEY      May 28, 2026, 16:20   May 28, 2026, 16:20
# a209b1b3-062c-46f6-a2f2-3b0061751190   JWT_SECRET          May 28, 2026, 16:19   May 28, 2026, 16:19

# Delete a secret
telnyx-edge secrets delete OLD_API_KEY
# ✓ Secret 'OLD_API_KEY' deleted successfully

Secrets are injected into function containers at deploy time — after adding or updating one, telnyx-edge ship each function that uses it.

Reading secrets

As environment variables — every language

Each secret is injected into all functions in your organization as an environment variable named after its key. No declaration needed:

const stripeKey = process.env.STRIPE_API_KEY;
if (!stripeKey) throw new Error("STRIPE_API_KEY not configured");

import os

stripe_key = os.environ["STRIPE_API_KEY"]

stripeKey := os.Getenv("STRIPE_API_KEY")
if stripeKey == "" {
    log.Fatal("STRIPE_API_KEY not configured")
}

String stripeKey = System.getenv("STRIPE_API_KEY");

Through the typed binding — TypeScript

TypeScript projects can additionally declare a [[secrets]] binding in func.toml and read the secret through env.SECRETS:

# func.toml
[[secrets]]
binding = "STRIPE_KEY"       # the handle your code uses
name    = "STRIPE_API_KEY"   # the key stored with `secrets add`

telnyx-edge types   # regenerates telnyx-env.d.ts from the manifest

import { env } from "@telnyx/edge-runtime";

const stripeKey = await env.SECRETS.get("STRIPE_KEY"); // get returns Promise

Both surfaces read the same store. The binding adds two things: env.SECRETS.get accepts only the literal union of declared handles — a typo’d handle fails to compile — and the in-code handle is decoupled from the stored key name, so you can swap name in the manifest without touching code. The binding SDK is TypeScript-only today; other runtimes use the injected environment variables. Enforced when [[secrets]] is declared: a binding named SECRETS and duplicate [[secrets]] handles are hard errors — ship fails. An [env_vars] entry named SECRETS only warns (it shadows the env.SECRETS namespace), so rename it. See Bindings for how the env namespace works.

Rotating a secret

add with an existing key overwrites its value:

telnyx-edge secrets add DATABASE_PASSWORD "new-password"
telnyx-edge ship                # redeploy each function that uses it
curl https://my-func-myorg.telnyxcompute.com/health   # verify

Scoping and local development

Secrets are organization-scoped. There is no per-environment scoping (dev/staging/prod) today — if you need separation, encode it in the key name (DEV_DATABASE_PASSWORD, PROD_DATABASE_PASSWORD) and pick one in code. There is no local secrets emulation in the CLI. When running a function locally, export the same names as ordinary environment variables:

STRIPE_API_KEY="sk_test_..." node index.js

Troubleshooting

Symptom	Fix
Variable missing in the function	`telnyx-edge secrets list` to confirm the key exists, then `telnyx-edge ship` — values are injected at deploy time.
Stale value	`secrets add` again, then `ship`.
`env.SECRETS.get` doesn’t type-check	Re-run `telnyx-edge types` after editing `[[secrets]]`; pass the `binding` handle, not the `name`.
CLI rejects the command	`telnyx-edge auth status`, then `telnyx-edge auth login` if needed.

Next Steps

Environment variables — the full picture of what lands in your container’s environment
Bindings — the declare → types → env pattern all bindings share
Configuration — [[secrets]] and every other manifest key

CI/CD

Source: https://developers.telnyx.com/docs/edge-compute/deploy.md

Every Edge Compute deployment from CI is the same three steps: install a pinned telnyx-edge binary, authenticate with auth api-key set, and run ship. This page gives you those steps as working pipelines for GitHub Actions, GitLab CI, and CircleCI, plus the patterns for staging/production and rollback.

The three steps every pipeline runs

TELNYX_EDGE_VERSION=v0.2.3

# 1. Install — release assets are version-stamped and extract into a versioned directory
curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${TELNYX_EDGE_VERSION}/telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv "telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/

# 2. Authenticate — the CLI does NOT read $TELNYX_API_KEY from the environment
telnyx-edge auth api-key set "$TELNYX_API_KEY"

# 3. Deploy the function in the current directory (or --from-dir )
telnyx-edge ship

Three facts these steps depend on:

The CLI ships as GitHub release binaries only — it is not on npm and there is no package manager formula. There is also no un-versioned “latest” asset: releases/latest/download/... URLs return 404. Pin a version in a TELNYX_EDGE_VERSION variable so bumping is a one-line change. For arm64 runners, use the linux-arm64 asset.
telnyx-edge does not read a TELNYX_API_KEY environment variable on its own. Store your API key as a CI secret and run telnyx-edge auth api-key set "$TELNYX_API_KEY" as a pipeline step — it persists the key to ~/.telnyx-edge/config.toml for the rest of the job.
ship has no environment flag. It deploys the function identified by func.toml in the shipped directory, and its flags are --from-dir and --timeout only. Staging and production are separate functions.

On success, ship prints the function’s live URL (https://{func-name}-{org-nickname}.telnyxcompute.com — see Routes & Domains). The URL is stable across deploys.

GitHub Actions

A complete workflow that tests on every push and deploys on pushes to main. Only the install, authenticate, and ship steps are Telnyx-specific — the test job is ordinary npm and assumes a committed lockfile and a test script (the scaffold ships neither); substitute your project’s own checks.

# .github/workflows/deploy.yml
name: Deploy Edge Function

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  TELNYX_EDGE_VERSION: v0.2.3

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install telnyx-edge
        run: |
          curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${TELNYX_EDGE_VERSION}/telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64.tar.gz" | tar xz
          sudo mv "telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/

      - name: Authenticate
        env:
          TELNYX_API_KEY: ${{ secrets.TELNYX_API_KEY }}
        run: telnyx-edge auth api-key set "$TELNYX_API_KEY"

      - name: Deploy
        run: telnyx-edge ship

Add the secret under Settings → Secrets and variables → Actions → New repository secret, named TELNYX_API_KEY.

GitLab CI

# .gitlab-ci.yml
stages:
  - deploy

variables:
  TELNYX_EDGE_VERSION: v0.2.3

deploy:
  stage: deploy
  image: ubuntu:24.04
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  before_script:
    - apt-get update -qq && apt-get install -y -qq curl ca-certificates
    - curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${TELNYX_EDGE_VERSION}/telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64.tar.gz" | tar xz
    - mv "telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/
    - telnyx-edge auth api-key set "$TELNYX_API_KEY"
  script:
    - telnyx-edge ship

Define TELNYX_API_KEY as a masked variable under Settings → CI/CD → Variables. The ubuntu:24.04 image runs as root, so no sudo is needed.

CircleCI

# .circleci/config.yml
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/base:current
    environment:
      TELNYX_EDGE_VERSION: v0.2.3
    steps:
      - checkout
      - run:
          name: Install telnyx-edge
          command: |
            curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${TELNYX_EDGE_VERSION}/telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64.tar.gz" | tar xz
            sudo mv "telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/
      - run:
          name: Authenticate
          command: telnyx-edge auth api-key set "$TELNYX_API_KEY"
      - run:
          name: Deploy
          command: telnyx-edge ship

workflows:
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Set TELNYX_API_KEY as a project environment variable (Project Settings → Environment Variables) or in a context.

Staging and production

There is no --env flag and no environment promotion — ship always deploys the function that func.toml names. Environments are separate functions, e.g. my-api-staging and my-api, each with its own URL, secrets bindings, and revision history. Register both once, locally (new-func creates the function server-side and writes its UUID func_id into that directory’s func.toml — this is a one-time setup step, not a CI step):

telnyx-edge new-func -l=ts -n=my-api-staging
telnyx-edge new-func -l=ts -n=my-api

Keep one codebase and both generated func.toml files in the repo; each pipeline job copies the matching one into place before shipping:

my-api/
├── index.ts
├── package.json
├── func.toml                 # production — func_id of my-api
└── deploy/
    └── func.staging.toml     # staging — func_id of my-api-staging

Because bindings are declared in func.toml, the two files can also point at per-environment resources — for example a separate KV namespace id per environment.

# .github/workflows/deploy.yml — staging on main, production on v* tags
name: Deploy

on:
  push:
    branches: [main]
    tags: ['v*']

env:
  TELNYX_EDGE_VERSION: v0.2.3

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install telnyx-edge
        run: |
          curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${TELNYX_EDGE_VERSION}/telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64.tar.gz" | tar xz
          sudo mv "telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/
      - name: Authenticate
        env:
          TELNYX_API_KEY: ${{ secrets.TELNYX_API_KEY }}
        run: telnyx-edge auth api-key set "$TELNYX_API_KEY"
      - name: Ship the staging function
        run: |
          cp deploy/func.staging.toml func.toml
          telnyx-edge ship

  deploy-production:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install telnyx-edge
        run: |
          curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${TELNYX_EDGE_VERSION}/telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64.tar.gz" | tar xz
          sudo mv "telnyx-edge-${TELNYX_EDGE_VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/
      - name: Authenticate
        env:
          TELNYX_API_KEY: ${{ secrets.TELNYX_API_KEY }}
        run: telnyx-edge auth api-key set "$TELNYX_API_KEY"
      - name: Ship the production function
        run: telnyx-edge ship

If you prefer fully separate directories over the func.toml swap, keep one function directory per environment and ship each with telnyx-edge ship --from-dir . If staging and production live in different Telnyx accounts, store one API key secret per account and reference the right one in each job.

Rollback

Every successful ship produces an immutable revision. Rolling back retargets traffic to a previous revision instantly — no rebuild, no re-upload:

# List recent revisions (newest first) with their ids
telnyx-edge revisions list my-api

# Retarget traffic to a previous revision
telnyx-edge rollback my-api a1b2c3d

Only revisions that reached deploy_ok can be rolled back to. You can wire these commands into a manually triggered pipeline job (e.g. workflow_dispatch on GitHub Actions), but they work just as well from a laptop — rollback does not need your source tree. A git revert + re-ship also works, but it goes through a full build; rollback is the fast path.

Smoke test after deploy

The function URL is stable, and the TypeScript/JavaScript scaffold answers /health with 200 — on other runtimes, point the check at a route your function serves. A post-deploy check is one step:

- name: Smoke test
  run: curl -fsS --retry 5 --retry-delay 2 --retry-all-errors https://my-api-.telnyxcompute.com/health

If it fails, roll back with telnyx-edge rollback as above. There is no platform metrics or logs surface to poll — see Observability for what your function should emit instead.

CI secrets vs. function secrets

Two different things:

	Where it lives	What it’s for
`TELNYX_API_KEY`	Your CI platform’s secret store	Lets the pipeline run `auth api-key set` and `ship`
Function secrets	The Telnyx platform, via `telnyx-edge secrets add`	Values your function reads at runtime

Function secrets are not deployed from CI variables — manage them with the CLI (the arguments are positional). Values are injected into function containers at deploy time, so re-ship a function after changing a secret it uses. See Secrets.

Troubleshooting

Symptom	Fix
`ship` fails with an authentication error	The CLI does not pick up `$TELNYX_API_KEY` from the environment. Run `telnyx-edge auth api-key set "$TELNYX_API_KEY"` as a prior step; `telnyx-edge auth status` confirms.
Install step 404s	The un-versioned `releases/latest/download/...` URL does not exist. Use the version-stamped asset URL shown above.
Function stuck in `build_failed` or `deploy_failed`	`telnyx-edge reset-func` tears down the failed deploy and returns the function to `created` (id, name, and config preserved), then re-ship.
`ship` monitoring times out	Default monitoring timeout is 5 minutes. Raise it with `--timeout` (e.g. `telnyx-edge ship --timeout 10m`).
Obscure failures	Re-run with `-v` for verbose logging.

Next Steps

CLI reference — every command and flag.
Versions & Rollback — how revisions and rollback work.
Secrets — runtime secrets for your functions.
Observability — what you can (and can’t) see after a deploy.

Routes & Domains

Source: https://developers.telnyx.com/docs/edge-compute/configuration/routing.md

Every function deployed with telnyx-edge ship gets a public HTTPS URL. Requests to that URL are the only trigger — there are no cron, queue, or event triggers today. If you need scheduled invocation, point an external scheduler (for example, a GitHub Actions cron job) at the URL.

Public URL pattern

https://{func-name}-{org-nickname}.telnyxcompute.com

Component	Description
`func-name`	The `func_name` from your `func.toml`
`org-nickname`	Your Telnyx organization’s nickname

A function named hello-world in the organization acme is served at:

https://hello-world-acme.telnyxcompute.com

telnyx-edge ship prints the URL after a successful deploy:

📡 Your function is live at:
   https://hello-world-acme.telnyxcompute.com

💡 Test your function:
   curl https://hello-world-acme.telnyxcompute.com

telnyx-edge list shows the invoke URL for every function in your organization.

Calling your function

All HTTP methods and paths under the function’s URL are routed to your server — path handling is up to your code (see HTTP handler):

# GET request
curl https://hello-world-acme.telnyxcompute.com

# POST request with JSON body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "test"}' \
  https://hello-world-acme.telnyxcompute.com/anything

Requests time out after 30 seconds by default (60 seconds maximum) — see Limits.

Custom domains

There is no custom domain support today — functions are reachable only at their telnyxcompute.com URL. To serve a function from your own domain, put a proxy you operate (CDN or reverse proxy) in front of it.

Region placement

You can’t pin a function to a region today; the platform chooses placement.

Next Steps

HTTP handler — the entrypoint contract behind the URL
Versions & Rollback — the URL always points at the active revision
Limits — request timeout and payload constraints

Versions & Rollback

Source: https://developers.telnyx.com/docs/edge-compute/configuration/versions.md

Every successful telnyx-edge ship produces an immutable revision. telnyx-edge revisions list shows a function’s deploy history; telnyx-edge rollback retargets traffic to a previous revision without rebuilding or re-uploading anything.

Listing revisions

telnyx-edge revisions list my-func

Prints the most recent revisions, newest first: the revision ID, when it was shipped, who shipped it, and its deploy status. The revision currently serving traffic is marked with *. Revision IDs are short identifiers like a1b2c3d — you pass one to rollback.

Rolling back

telnyx-edge rollback my-func a1b2c3d
# → Rollback of 'my-func' to revision a1b2c3d accepted; traffic is switching across clusters.
#   Run 'telnyx-edge revisions list my-func' to confirm the active revision.

Traffic is instantly retargeted to the existing, immutable revision across all clusters — there is no rebuild and no re-upload. Two constraints:

The target must have reached deploy_ok. A revision whose build or deploy failed never served traffic and can’t be rolled back to; revisions list shows each revision’s deploy status.
Rollback doesn’t touch your source. Your working tree and git history are unchanged. The next ship deploys whatever is on disk — as a new revision — regardless of which revision is currently active.

Rolling forward

To move forward again, either ship — every successful ship creates a new revision and moves traffic to it — or rollback to any other revision that reached deploy_ok.

Recovering a failed function

Rollback assumes the function has a healthy revision to return to. A function stuck in a terminal failure state (build_failed, deploy_failed, delete_failed) can instead be reset:

telnyx-edge reset-func broken-func

This tears down the function’s deployed resources and returns it to the created state — preserving its ID, name, and config — so you can fix the code and ship again. A healthy function (build_ok/deploy_ok) can’t be reset; use delete-func if you want it gone.

Next Steps

CI/CD — ship from a pipeline; rollback is your escape hatch
Routes & Domains — the function URL always points at the active revision
CLI reference — ship, revisions, rollback, and reset-func in full

Overview

Source: https://developers.telnyx.com/docs/edge-compute/runtime.md

Most serverless platforms hand you a sandbox: a restricted runtime, a fixed set of provided APIs, one supported way to return a response. Edge Compute doesn’t. A function is a real Linux container running your language’s own runtime — so the bulk of your “runtime API” is just the standard library and any dependency you install, exactly as it behaves on any Linux box. What the platform adds on top is small and explicit, and this section documents it end to end:

An execution environment — how containers start, stay warm, scale, and get a request budget. This is the architecture your code runs inside.
An entrypoint contract — which file the platform runs and how a request reaches your code, per language.
Bindings — declared connections to platform resources: the Telnyx API, secrets, KV, and object storage, with credentials injected for you so nothing sensitive lives in your code.

Everything else — HTTP parsing, crypto, file I/O, database drivers — comes from your language, not from the platform.

Real containers

Because a function is a real container:

Native runtimes — Node.js, Go, Python, and Java (Quarkus) run as themselves. No fetch-only sandbox, no restricted language subset.
Any dependency that installs — npm packages, Go modules, PyPI packages, Maven artifacts.
POSIX environment — environment variables, plus file I/O in the working directory and /tmp. The root filesystem is read-only and writes are ephemeral — they don’t survive the container being recycled, so persist real data in KV or a bucket.
Outbound network — HTTP clients, TCP sockets, DNS resolution.

The trade-off is container lifecycle: instances cold-start, stay warm between requests, and are recycled. Execution model covers what that means for initialization and in-memory state.

The entrypoint contract

HTTP is the only trigger. What “handling a request” means differs by language:

Language	`new-func -l`	Entrypoint	Server owned by
TypeScript	`ts`	`index.ts` — your own `node:http` server on `process.env.PORT \|\| 8080`	You
JavaScript	`js`	`index.js` — same contract as TypeScript	You
Go	`go`	`handler.go` — exported `Handle(w, r)` in `package function`	Platform
Python	`python`	`function/func.py` — ASGI `new()` factory	Platform
Java	`quarkus`	Quarkus Funqy `@Funq` method	Quarkus

The exact per-language contract — files, signatures, health probes, bodies, the request budget — is specified in HTTP handler.

Bindings

A function reaches platform resources — the Telnyx API, secrets, KV, and object storage — through bindings you declare in the project manifest. The platform injects the credential, so no keys or tokens appear in your code. How you reach a binding depends on the language:

TypeScript gets a typed handle for each declared binding, resolved at runtime.
Go, Python, and Java reach the same resources through injected environment variables (the Telnyx API key, each secret) and REST.

Bindings documents every binding type and how to declare it; Environment variables and Secrets cover configuration.

In this section

How your code runs: cold starts, warm reuse, scaling, the request budget, and where state lives. The per-language entrypoint contract — files, signatures, health probes. Reach platform resources — Telnyx API, secrets, KV, object storage — from any language.

Execution Model

Source: https://developers.telnyx.com/docs/edge-compute/runtime/execution-model.md

An Edge Compute function is a Linux container running an HTTP server — one you run yourself in TypeScript and JavaScript, one run for you in Go, Python, and Java. The platform starts containers when traffic arrives, reuses them while it continues, and reclaims them — down to zero — when it stops. Everything on this page follows from that.

Request path

Route — a request to https://-.telnyxcompute.com reaches the platform (routing).
Place — a warm container takes it, or a new one starts (a cold start).
Execute — the server process handles the request and writes the response.
Keep warm — the container stays up for subsequent requests until it is recycled.

Container lifecycle

Cold start

A cold start is the first request’s cost of a new container: the image starts, the language runtime boots, your module-level code runs, and then the request is served. Put expensive setup — HTTP clients, connection pools, parsed config — at module scope so it runs once per container instead of once per request:

import * as http from "node:http";

// Module scope — runs once per container, at cold start
const startedAt = Date.now();
const cache = new Map(); // per-container cache — not durable

const server = http.createServer((req, res) => {
  // Handler scope — runs per request
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ containerAgeMs: Date.now() - startedAt }));
});

server.listen(process.env.PORT || 8080);

Curl that function twice: a near-zero containerAgeMs means the request paid a cold start; a growing one means the container was reused. The same split exists in every runtime — package-level vars and init() in Go, module scope or the optional start(cfg) hook in Python, application-scoped state in Quarkus. The per-language entrypoint contracts are in HTTP handler.

Warm reuse

While traffic continues, requests land on existing containers and skip initialization. Module state persists between requests on the same container — treat it as a cache keyed by container, nothing more. Two requests may or may not share a container, and the platform gives you no way to control which.

Recycling and scale to zero

Containers are reclaimed without notice: after idling, when a new revision is shipped (telnyx-edge ship — see Versions), or by platform scaling decisions. At zero traffic a function scales to zero containers; the next request pays a cold start. Treat container memory like a process that can be killed at any instant: only what you wrote to durable storage is real. See Where state lives for what “durable storage” means here. In Python, your function class may define an optional stop() hook, called on scale-down or update — use it for best-effort cleanup, never for durability.

Scaling

The platform scales the container count with concurrent load. There is no concurrency knob to configure — scaling is automatic.

Traffic pattern	Platform response
Spike	New containers start — expect cold starts
Sustained	Containers stay warm
Falling	Containers are gradually reclaimed
Zero	Scale to zero after an idle period

Request timeout

A function must respond within 30 seconds by default, 60 seconds maximum; a request that exceeds the budget is terminated with a 504. There is no func.toml field for this — see Limits for the full table. Budget outbound calls below the deadline so you return a real error instead of being cut off:

const upstream = await fetch("https://api.example.com/data", {
  signal: AbortSignal.timeout(25_000), // fail at 25 s, inside the 30 s budget
});

Triggers

HTTP is the only trigger — there are no cron, queue, or event triggers. A Telnyx webhook (a messaging profile or Call Control application pointed at your function URL) is just an HTTP request, so your function handles it like any other — see Receiving messages and Handling calls. For periodic work, call the URL from an external scheduler (a GitHub Actions cron job is enough), or use a Stateful Actor alarm to fire a callback on the platform itself.

Where state lives

Module state dies with the container, so anything that must survive needs a home:

Data	Use	Why
Per-entity state, counters, coordination	Stateful Actors (Beta)	One instance per name, serialized calls, durable writes — correct under concurrency
Cache entries, config, feature flags, sessions	KV	Globally distributed reads; opaque values up to 1 MiB with optional TTL
Files, media, large objects	Cloud Storage buckets	S3-compatible object storage

Don’t build counters or per-entity coordination on KV — concurrent read-modify-write races there, which is exactly the problem Stateful Actors exist to solve.

Next Steps

HTTP handler — the entrypoint contract per language
Limits — timeouts, memory, and payload caps
Versions — revisions, ship, and rollback

HTTP Handler

Source: https://developers.telnyx.com/docs/edge-compute/runtime/http-handler.md

HTTP is the only way a function is invoked. Requests arrive at https://-.telnyxcompute.com (see Routing) and are handed to your entrypoint — but what “your entrypoint” means differs by language. In TypeScript and JavaScript you own and run the HTTP server (the CLI scaffolds a working one); in Go, Python, and Java the server is run for you and your code is called per request. telnyx-edge new-func -l generates a working entrypoint for each language. The code on this page is that scaffold — start from it rather than a blank file.

The contract at a glance

Language	File	You implement	Server owned by	Health probes
TypeScript / JavaScript	`index.ts` / `index.js` (project root)	An HTTP server on `process.env.PORT \|\| 8080`	You	You — return `200` for `/health` and paths under it
Go	`handler.go`	`func Handle(w http.ResponseWriter, r *http.Request)` in `package function`	Platform	Handled for you — no health route in your code
Python	`function/func.py`	`new()` factory returning an object with `async def handle(self, scope, receive, send)`	Platform	Platform — probes never reach `handle()`
Java	`src/main/java/functions/Function.java`	A method annotated `@Funq` (Quarkus Funqy)	Quarkus	SmallRye Health at `/health/*`, pre-configured

The scaffold, by language

Each tab is one language’s entrypoint contract and the scaffold new-func generates for it. You own the server. There is no framework-provided handler(request) entrypoint and no Response object to return — your function is a container running a plain node:http server (or any server framework you install). Two things are contractual:

Listen on process.env.PORT, falling back to 8080.
Answer /health (and paths under it) with a 200. The platform’s liveness and readiness probes hit it — a function that doesn’t answer isn’t routed traffic and can be restarted. Keep the probe path fast: respond before any other work.

index.ts lives at the project root, next to func.toml — not in src/. The scaffold, lightly condensed (comments trimmed):

import * as http from 'node:http';

interface ResponseData {
  message: string;
  data?: any;
}

const server = http.createServer(async (req: http.IncomingMessage, res: http.ServerResponse) => {
  // Liveness/readiness probes — answer before any other work
  if (req.url === '/health' || req.url?.startsWith('/health/')) { res.writeHead(200); res.end(); return; }

  const responseData: ResponseData = {
    message: 'Hello from Telnyx Edge Compute!'
  };

  // POST: read and echo the request body
  if (req.method === 'POST') {
    let body = '';

    req.on('data', (chunk: Buffer) => {
      body += chunk.toString();
    });

    req.on('end', () => {
      if (body) {
        try {
          responseData.data = JSON.parse(body);
        } catch (error) {
          responseData.data = body;   // not JSON — echo as text
        }
      }

      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify(responseData));
    });
  } else {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(responseData));
  }
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

The JavaScript scaffold (-l js) is the same file minus type annotations, at index.js (same project-root location). Request bodies arrive as data events carrying Buffer chunks. The scaffold accumulates them as a string, which is fine for text and JSON — for binary bodies collect the buffers instead (chunks.push(chunk) then Buffer.concat(chunks)), because toString() corrupts non-UTF-8 bytes. The platform owns the server. You write an ordinary net/http handler — exported as Handle, in package function, with no main(). The platform binds the port and routes requests to Handle; the scaffold defines no health route and doesn’t need one. handler.go — the scaffold, lightly condensed (comments trimmed):

package function

import (
  "encoding/json"
  "io"
  "log"
  "net/http"
)

// Response represents the function response structure
type Response struct {
  Message string      `json:"message"`
  Data    interface{} `json:"data,omitempty"`
}

// Handle answers every HTTP request routed to the function.
func Handle(w http.ResponseWriter, r *http.Request) {
  log.Printf("Serving a new request: %v > %v @ %v", r.Host, r.Method, r.URL.Path)

  w.Header().Set("Content-Type", "application/json")

  response := Response{
    Message: "Hello from Telnyx Edge Compute!",
  }

  // POST: read and echo the request body
  if r.Method == "POST" {
    body, err := io.ReadAll(r.Body)
    if err != nil {
      log.Printf("Error reading request body: %v", err)
    } else if len(body) > 0 {
      var jsonData interface{}
      if err := json.Unmarshal(body, &jsonData); err == nil {
        response.Data = jsonData
      } else {
        response.Data = string(body) // not JSON — echo as text
      }
    }
  }

  responseBytes, err := json.Marshal(response)
  if err != nil {
    http.Error(w, "Internal Server Error", http.StatusInternalServerError)
    return
  }

  w.Write(responseBytes)
}

go.mod declares module function (Go 1.24). Standard net/http semantics apply: read the body from r.Body, set headers with w.Header().Set(...) before the first write. The contract is ASGI. Your project is a function/ package whose func.py exposes a module-level new() factory; the runtime calls it when an instance starts, keeps the returned object, and dispatches every HTTP request — except liveness and readiness probes, which the platform answers itself — to its handle coroutine. There is no handler(request) returning a dict, and no requirements.txt — dependencies go in pyproject.toml (the scaffold uses hatchling). function/func.py — the scaffold, trimmed (scope validation and logging removed):

import json

def new():
    """Required. Called when an instance starts; the returned object
    receives all requests via its handle() coroutine."""
    return Function()

class Function:
    async def handle(self, scope, receive, send):
        """Called for every HTTP request except liveness/readiness probes."""
        method = scope.get('method', 'GET')

        response_data = {"message": "Hello from Telnyx Edge Compute!"}

        # POST: the body arrives in chunks over the ASGI receive channel
        if method == 'POST':
            body = b''
            while True:
                message = await receive()
                if message['type'] == 'http.request':
                    body += message.get('body', b'')
                    if not message.get('more_body', False):
                        break

            if body:
                try:
                    response_data["data"] = json.loads(body)
                except (json.JSONDecodeError, UnicodeDecodeError):
                    response_data["data"] = body.decode('utf-8', errors='replace')

        await send({
            'type': 'http.response.start',
            'status': 200,
            'headers': [
                [b'content-type', b'application/json'],
            ],
        })
        await send({
            'type': 'http.response.body',
            'body': json.dumps(response_data).encode(),
        })

    def start(self, cfg):
        """Optional. Called when an instance starts (scale-up, update).
        cfg is a dict of all environmental configuration."""

    def stop(self):
        """Optional. Called when an instance stops (scale-down, update,
        manual cancel)."""

function/__init__.py re-exports the factory: from .func import new.

Hook	Required	Called when
`new()`	Yes	Instance start — returns the object that handles requests
`handle(self, scope, receive, send)`	Yes	Every request (async, ASGI)
`start(cfg)`	No	Instance start — `cfg` is a dict of all environmental configuration
`stop()`	No	Instance stop — scale-down, update, or manual cancel

Functions are Quarkus Funqy functions: a plain class with a method annotated @Funq that takes a bean and returns a bean. Quarkus owns the server, deserializes the JSON request body into your input bean, and serializes your return value back to JSON. src/main/java/functions/Function.java — the scaffold:

package functions;

import io.quarkus.funqy.Funq;

public class Function {

    @Funq
    public Output function(Input input) {

        String defaultMessage = "Hello from Telnyx Edge Compute!";

        // Null or empty input — return the default message
        if (input == null || input.getMessage() == null || input.getMessage().trim().isEmpty()) {
            return new Output(defaultMessage);
        }

        // Echo back the input message
        return new Output(input.getMessage());
    }

}

Input and Output are plain beans in the same package — a message field with a no-arg constructor, getter, and setter. Invocation is JSON in, JSON out:

curl -s https://demo-quarkus-.telnyxcompute.com \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'
# → {"message":"hello"}

Two scaffold defaults worth knowing:

application.properties selects the exported method by name: quarkus.funqy.export=function. Rename the method, update the property.
Health endpoints come from SmallRye Health, pre-configured at /health/liveness and /health/readiness — leave them in place.

Funqy is a typed JSON model: your method sees the deserialized bean, not raw bytes, URL paths, or headers. For raw HTTP semantics — routing on paths, custom headers, binary bodies — use the TypeScript, JavaScript, Go, or Python contract instead.

Bodies, headers, and binary data

These apply to the raw-HTTP contracts — TypeScript, JavaScript, Go, and Python. Java/Funqy is the exception: it’s typed JSON in/out, so raw bodies, binary responses, and custom headers aren’t available from a @Funq method (see the Java tab).

Bodies pass through raw, both directions. There is no base64 envelope and no JSON wrapping between the caller and your code. To serve binary, set the Content-Type and write the bytes:
res.writeHead(200, { "Content-Type": "image/png" }); res.end(pngBuffer); // raw bytes — no base64
Headers are yours. Whatever your server (or Handle, or http.response.start) sets is what the caller receives. There is no platform header rewriting to work around.
Bodies are size-capped. Request and response body limits are listed in Limits.

The request budget

A function has 30 seconds by default to respond, and 60 seconds at most. Past the budget the request is terminated and the caller gets a 504. This is a platform limit, not a func.toml field — there is no timeout_seconds setting. For work that can run long, set your own internal timeout a few seconds under the platform’s and return an error or partial result instead of being cut off mid-response. Exact numbers and the other caps — memory, body size, deploy rate — are in Limits.

Bindings — the typed env surface: Telnyx API, secrets, KV
Execution model — lifecycle, cold starts, concurrency
Limits — timeouts, body size, memory

Overview

Source: https://developers.telnyx.com/docs/edge-compute/runtime/bindings.md

A binding maps a name you declare in func.toml to an authenticated resource handle, resolved by the runtime — the credential is injected for you and never appears in your code, bundle, or logs. Each binding resolves on the env object (from @telnyx/edge-runtime) — env.MY_TELNYX, env.SECRETS, and so on. The env object and telnyx-edge types are TypeScript-only today. Other runtimes (js, go, python, quarkus) don’t get the typed env handle, but reach the same resources through the credentials injected into the container — see Bindings from other languages.

Every binding works the same way

# func.toml — 1. declare
[telnyx]
binding = "MY_TELNYX"

# 2. generate types
telnyx-edge types

// 3. use it — typed and authenticated
import { env } from "@telnyx/edge-runtime";
const { data } = await env.MY_TELNYX.availablePhoneNumbers.list({
  filter: { country_code: "US" },
});

The binding name (MY_TELNYX) is yours to choose; it becomes the property on env. telnyx-edge types writes telnyx-env.d.ts from the manifest — re-run it after every binding change. Typing for [storage.kv.] blocks requires CLI v0.2.3 or later. The SDK types .data as T | undefined for list calls. Under tsc --strict, indexing into data (e.g. data.length) fails with TS18048: 'data' is possibly 'undefined'. Coalesce before use: const arr = list.data ?? [];.

Catalogue

Resource	Declaration	On `env`
Telnyx API	`[telnyx]`	`env.` — a pre-authenticated Telnyx SDK client
Secrets	`[[secrets]]`	`env.SECRETS.get("")` → `Promise`
Key-Value storage	`[storage.kv.]`	`env.` — a `KvNamespace`: `get`, `put`, `delete`, `list`
Object storage	`[storage.cloudstorage.]`	`env.` — a `CloudStorageBucket`: `get`, `put`, `head`, `delete`, `list`
Stateful Actors (Beta)	`[[actors]]` — umbrella `telnyx.toml` only	`env.` — an actor namespace: one instance per name, addressed via `idFromName`

Manifest: `func.toml` or `telnyx.toml`

Bindings are declared in your project manifest. telnyx-edge types reads either form and types env. for each declared binding.

func.toml (classic) — the standard [edge_compute] project file. Can declare [telnyx], [[secrets]], [storage.kv.], and [storage.cloudstorage.].
telnyx.toml (umbrella) — a manifest with top-level name and main. Declares the same bindings, plus [[actors]] — actor classes are imported from main, which is why actors require the umbrella form.

# telnyx.toml — umbrella manifest
name = "my-app"
main = "src/index.ts"

[telnyx]
binding = "MY_TELNYX"

[[secrets]]
binding = "GREETING"
name    = "DEMO_GREETING"

[storage.kv.CACHE]
id = ""   # from `telnyx-edge storage kv list`

Bindings from other languages

The env SDK surface is TypeScript-only, but the credentials behind it are not:

Telnyx API — declaring [telnyx] also injects a TELNYX_API_KEY environment variable into the container at runtime. Any language can call the Telnyx REST API with it as a bearer token — see Using the Telnyx API.
Secrets — every secret is also injected as a plain environment variable into all your functions (os.environ["DEMO_GREETING"], os.Getenv("DEMO_GREETING"), …). env.SECRETS.get() and the environment variable are two views of the same value.
KV — any language can use the KV REST API with the injected TELNYX_API_KEY.
Object storage — the typed env binding is TypeScript only; from any language, reach the same buckets over the S3-compatible API with your own access keys.
Stateful Actors — TypeScript only; there is no REST fallback today.

Bindings vs secrets

Binding — a Telnyx or platform resource, authenticated for you (env.MY_TELNYX).
Secret — a value you supply (env.SECRETS.get("STRIPE_KEY")).

Use a binding for platform resources; use a secret for your own third-party credentials.

Next Steps

Telnyx API quick start — declare [telnyx] and make your first authenticated call
KV quick start — create a namespace, bind it, read and write
Object storage binding — bind a bucket and read, write, and list objects from env
Secrets — add, rotate, and access secrets
Stateful Actors — per-entity state and coordination

Overview

Source: https://developers.telnyx.com/docs/edge-compute/telnyx-api.md

The Telnyx API binding puts a ready-to-use, authenticated Telnyx client on env. You never handle an API key — the binding injects credentials at the edge and keeps them out of your code, bundle, and logs.

import { env } from "@telnyx/edge-runtime";

await env.MY_TELNYX.messages.send({
  from: "+13125550100",
  to: "+13125550101",
  text: "Hello from Edge Compute",
});

Free-formed name — MY_TELNYX is whatever you set as binding in func.toml. It becomes the property on env.
Typed — telnyx-edge types types env.MY_TELNYX as the Telnyx client.
One per organization — every function in the org shares it.

Start with the Quick start. The org-level credential behind the binding (bindings create / validate / update) is account-level and rarely touched — see the CLI reference.

Quick Start

Source: https://developers.telnyx.com/docs/edge-compute/telnyx-api/quick-start.md

A complete function that returns your Telnyx account balance — declared, typed, shipped, and called.

1. Create a function

telnyx-edge new-func --language ts --name balance-check
cd balance-check

2. Declare the binding

Add a [telnyx] block to the generated func.toml:

# func.toml
[edge_compute]
func_id = "60c5ce48-…"   # created by new-func
func_name = "balance-check"

[telnyx]
binding = "MY_TELNYX"

3. Generate types

telnyx-edge types

env.MY_TELNYX is now typed as the Telnyx client.

4. Write the handler

// index.ts
import * as http from "node:http";
import { env } from "@telnyx/edge-runtime";

const port = Number(process.env.PORT ?? 8080);

http.createServer(async (req, res) => {
  // Match /health and any /health/* probe path the platform requires
  // (the scaffold generates this guard — keep it).
  if (req.url === "/health" || req.url?.startsWith("/health/")) {
    return res.writeHead(200).end();
  }

  const { data } = await env.MY_TELNYX.balance.retrieve();
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify(data));
}).listen(port);

5. Ship

telnyx-edge ship

6. Call it

ship prints your function URL. Hit it:

curl https://balance-check-.telnyxcompute.com

{
  "credit_limit": "1000.00",
  "frozen": "0.00",
  "currency": "USD",
  "available_credit": "1100.00",
  "pending": "0.00",
  "balance": "100.00",
  "record_type": "balance"
}

API Reference

Source: https://developers.telnyx.com/docs/edge-compute/telnyx-api/api-reference.md

env.MY_TELNYX is a ready-to-use, authenticated Telnyx client handle — call it like any Telnyx API client, with auth already wired in (no new Telnyx(...), no API key to manage). Calls take the shape env.MY_TELNYX..(...), using resource and method names — not raw HTTP paths:

“ — a camelCase property: messages, calls, balance, availablePhoneNumbers, …
“ — a method on the resource: .send, .dial, .list, .retrieve, …

The names don’t always track the HTTP API (messages.send is POST /messages, but messages.cancelScheduled is DELETE /messages/{id}), so discover them rather than guessing from endpoints:

Autocomplete — after telnyx-edge types, your editor completes env.MY_TELNYX. with every resource and method.
Client method reference (api.md) — lists every .(...) and the endpoint it maps to.
HTTP API reference — endpoint parameters and behavior.

import { env } from "@telnyx/edge-runtime";

await env.MY_TELNYX.messages.send({ from: "+13125550100", to: "+13125550101", text: "Hello" }); // POST /messages
await env.MY_TELNYX.calls.dial({ connection_id: "2985…", from: "+13125550100", to: "+13125550101" }); // POST /calls
await env.MY_TELNYX.availablePhoneNumbers.list({ filter: { country_code: "US" } });               // GET /available_phone_numbers
await env.MY_TELNYX.balance.retrieve();                                                            // GET /balance

Each method returns the API response; list and retrieve calls expose the payload on .data.

Errors

Calls reject on API errors. Catch and inspect:

try {
  await env.MY_TELNYX.messages.send({ from: "+13125550100", to: "+13125550101", text: "Hello" });
} catch (err) {
  // err.status (e.g. 400), err.message, err.error (parsed body)
}

Receiving Messages

Source: https://developers.telnyx.com/docs/edge-compute/telnyx-api/receiving-messages.md

Inbound SMS is webhook-driven: Telnyx POSTs a message.received event to your messaging profile’s webhook, and your Edge Compute function is that webhook. Replying to another Telnyx number is on-net — no 10DLC campaign required.

1. Write the handler

// index.ts
import * as http from "node:http";
import { env } from "@telnyx/edge-runtime";

const port = Number(process.env.PORT ?? 8080);
const received: any[] = []; // in-memory; use KV or SQL DB for durable storage

function body(req: http.IncomingMessage): Promise {
  return new Promise((r) => {
    let b = "";
    req.on("data", (c) => (b += c));
    req.on("end", () => r(b));
  });
}

http.createServer(async (req, res) => {
  // GET: see what's been received
  if (req.method === "GET") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ received }, null, 2));
    return;
  }

  // POST: Telnyx inbound webhook — parse it through the binding
  const evt = env.MY_TELNYX.webhooks.unsafeUnwrap<{ data: any }>(await body(req)).data;
  if (evt?.event_type === "message.received") {
    const p = evt.payload;
    const from = p.from.phone_number;
    const to = p.to[0].phone_number;
    received.unshift({ from, to, text: p.text, at: evt.occurred_at });

    // Auto-reply on-net (no 10DLC when the recipient is a Telnyx number)
    await env.MY_TELNYX.messages.send({ from: to, to: from, text: `You said: ${p.text}` });
  }
  res.writeHead(200);
  res.end();
}).listen(port);

Declare the binding in func.toml (see the Quick start):

[telnyx]
binding = "MY_TELNYX"

2. Ship

telnyx-edge ship

3. Point a messaging profile at it

Set a messaging profile’s inbound webhook to your function URL, then assign your number to that profile:

# webhook -> your function
curl -X POST https://api.telnyx.com/v2/messaging_profiles \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"inbound-demo","webhook_url":"https://YOUR-FUNC.telnyxcompute.com","whitelisted_destinations":["US"]}'

# assign your number to the profile (use the profile id from the response)
curl -X PATCH https://api.telnyx.com/v2/phone_numbers/YOUR-NUMBER-ID/messaging \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"messaging_profile_id":"YOUR-PROFILE-ID"}'

4. Test on-net

Send from another Telnyx number on your account to your function’s number:

curl -X POST https://api.telnyx.com/v2/messages \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"from":"+1ANOTHER_TELNYX_NUMBER","to":"+1YOUR_FUNC_NUMBER","text":"hello"}'

You get back “You said: hello” on-net, and GET https://YOUR-FUNC.telnyxcompute.com shows what arrived. The inbound event the function parses looks like:

{
  "data": {
    "event_type": "message.received",
    "occurred_at": "2026-06-19T16:06:17.464+00:00",
    "payload": {
      "from": { "phone_number": "+1..." },
      "to": [ { "phone_number": "+1..." } ],
      "text": "hello"
    }
  }
}

Only on-net replies skip 10DLC. Receiving is always free. Replying to a Telnyx number is on-net (no campaign). Replying to an off-net number — e.g. a personal mobile — is application-to-person traffic and requires 10DLC registration.

Keyword auto-reply

The handler above echoes every message. To answer commands instead, replace the messages.send call in step 1 with a keyword match:

const text = p.text.trim().toUpperCase();
if (text === "STOP") {
  // opt-out: send nothing
} else {
  const replies: Record = {
    HELP: "Commands: HOURS, LOCATION. Reply STOP to opt out.",
    HOURS: "Open Mon-Fri 9am-5pm ET.",
    LOCATION: "600 Congress Ave, Austin, TX",
  };
  await env.MY_TELNYX.messages.send({
    from: to,
    to: from,
    text: replies[text] ?? "Thanks for your message. Reply HELP for options.",
  });
}

This handles the STOP message itself but doesn’t remember it — store opted-out numbers in KV and check before every send.

Handling Calls

Source: https://developers.telnyx.com/docs/edge-compute/telnyx-api/handling-calls.md

Inbound voice is webhook-driven through Call Control: Telnyx POSTs call events to your Call Control application’s webhook, and your Edge Compute function is that webhook. On call.initiated you answer the call; on call.answered you play audio.

1. Write the handler

// index.ts
import * as http from "node:http";
import { env } from "@telnyx/edge-runtime";

const port = Number(process.env.PORT ?? 8080);
const AUDIO_URL = "https://YOUR-HOST/song.mp3"; // a reachable HTTPS mp3/wav you have rights to

function body(req: http.IncomingMessage): Promise {
  return new Promise((r) => {
    let b = "";
    req.on("data", (c) => (b += c));
    req.on("end", () => r(b));
  });
}

http.createServer(async (req, res) => {
  if (req.method === "GET") { res.writeHead(200).end(); return; } // health

  // parse the inbound webhook through the binding
  const evt = env.MY_TELNYX.webhooks.unsafeUnwrap<{ data: any }>(await body(req)).data;
  const id = evt?.payload?.call_control_id;

  if (evt?.event_type === "call.initiated" && id) {
    await env.MY_TELNYX.calls.actions.answer(id, {});
  } else if (evt?.event_type === "call.answered" && id) {
    await env.MY_TELNYX.calls.actions.startPlayback(id, { audio_url: AUDIO_URL });
  }

  res.writeHead(200);
  res.end();
}).listen(port);

Declare the binding in func.toml:

[telnyx]
binding = "MY_TELNYX"

2. Ship

telnyx-edge ship

3. Point a Call Control app at it

# create a Call Control app whose webhook is your function
curl -X POST https://api.telnyx.com/v2/call_control_applications \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"application_name":"voice-demo","webhook_event_url":"https://YOUR-FUNC.telnyxcompute.com"}'

# route your number to that app (connection_id = the app id from the response)
curl -X PATCH https://api.telnyx.com/v2/phone_numbers/YOUR-NUMBER-ID \
  -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" \
  -d '{"connection_id":"YOUR-CALL-CONTROL-APP-ID"}'

4. Test

Call the number from any phone. The function answers and plays your audio. audio_url must be a publicly reachable HTTPS .mp3 or .wav. The flow is two events — call.initiated (answer) then call.answered (play) — so handle both. To loop, hang up, or chain more actions, respond to later events (call.playback.ended, call.hangup) the same way.

Time-of-day routing

To route callers to a person instead of playing audio, replace both event branches in step 1 with a single transfer on call.initiated — Telnyx dials the destination and bridges the caller when it answers, so there’s nothing to do on call.answered:

const OFFICE = "+13125550100"; // business hours
const ON_CALL = "+13125550199"; // after hours

function businessHours(): boolean {
  const hour = Number(
    new Intl.DateTimeFormat("en-US", {
      timeZone: "America/New_York",
      hour: "numeric",
      hourCycle: "h23",
    }).format(new Date()),
  );
  return hour >= 9 && hour < 17;
}

if (evt?.event_type === "call.initiated" && id) {
  await env.MY_TELNYX.calls.actions.transfer(id, {
    to: businessHours() ? OFFICE : ON_CALL,
  });
}

If the transfer fails, you get a call.hangup webhook for the destination leg and the caller’s leg stays active — transfer to an alternate number or answer and play a message.

Observability

Source: https://developers.telnyx.com/docs/edge-compute/observability.md

Edge Compute has no customer-facing telemetry surface today: there is no telnyx-edge logs command, no log dashboard, and no metrics or traces. console.log output from a running function is not readable anywhere. What you can observe is built from three things — the CLI’s control-plane views, your function’s own health endpoint, and structured events your function emits over HTTPS to a collector you run.

Control-plane visibility

The CLI answers “is it deployed, and where does it answer” — not “what is it doing”:

Command	What it tells you
`telnyx-edge ship`	Build and deploy progress for one revision, ending in the live URL — build and deploy failures surface here
`telnyx-edge list`	Every function: id, name, status, creation time, invoke URL
`telnyx-edge inspect`	One function’s status, invoke URL, timestamps, and actor bindings — accepts a name or an id
`telnyx-edge revisions list`	Deploy history, newest first — each successful ship is an immutable revision you can roll back to
`telnyx-edge status`	CLI self-diagnostics: config file, authentication, connectivity to `api.telnyx.com` — it checks your CLI, not your functions

Add -v to any command for verbose client-side logging when a command itself misbehaves. None of this shows requests, errors, or output from the running container. For that, read on.

Health checks

The scaffolded TypeScript and JavaScript entrypoints answer /health before any other routing:

// index.ts — the scaffold's fast path
if (req.url === '/health' || req.url?.startsWith('/health/')) { res.writeHead(200); res.end(); return; }

Keep this route dependency-free — no KV reads, no outbound calls — so an external checker can tell “function down” apart from “dependency down”. The Quarkus scaffold serves /health through SmallRye Health; in Go and Python, add an equivalent route yourself. HTTP is the only trigger, so probing is external by design: point an uptime monitor — or a scheduled job such as a GitHub Actions cron — at https://-.telnyxcompute.com/health.

Emit events to a sink you run

Since nothing shows you a running function’s output, the pattern is to send structured events over HTTPS to a collector you control — any log store with an HTTP ingest endpoint works. Store the collector’s credential as a secret, never in code. Declare the secret in func.toml and store its value:

[[secrets]]
binding = "LOG_SINK_KEY"   # the handle you pass to env.SECRETS.get()
name    = "LOG_SINK_KEY"   # the secret's name from `secrets add`

telnyx-edge secrets add LOG_SINK_KEY ""
telnyx-edge types   # regenerate telnyx-env.d.ts so the handle type-checks

Then instrument the entrypoint. This emits one event per request — off the critical path, with a deadline, and never able to fail the response:

import * as http from "node:http";
import { randomUUID } from "node:crypto";
import { env } from "@telnyx/edge-runtime";

const SINK_URL = "https://logs.example.com/ingest"; // your collector

function emit(event: Record): void {
  // Fire-and-forget: telemetry must never delay or fail a response.
  void (async () => {
    const key = await env.SECRETS.get("LOG_SINK_KEY");
    await fetch(SINK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
      body: JSON.stringify({ ts: new Date().toISOString(), ...event }),
      signal: AbortSignal.timeout(2000), // a slow sink must not pile up sockets
    });
  })().catch(() => {}); // a dead sink must not take the function with it
}

const server = http.createServer((req, res) => {
  if (req.url === "/health" || req.url?.startsWith("/health/")) { res.writeHead(200); res.end(); return; }

  const requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
  const start = Date.now();
  res.setHeader("X-Request-ID", requestId);

  res.on("finish", () => {
    emit({
      level: res.statusCode < 500 ? "info" : "error",
      requestId,
      method: req.method,
      path: req.url,
      status: res.statusCode,
      durationMs: Date.now() - start,
    });
  });

  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ ok: true, requestId }));
});

server.listen(process.env.PORT || 8080);

What makes this pattern hold up:

Propagate a request id. Read X-Request-ID or generate one, return it in the response, and attach it to every event — a user-reported failure becomes findable in your sink.
Log metadata, not payloads. Method, path, status, duration. Never secret values, and not full request bodies, which may carry PII.
Buffering trades loss for volume. The per-request emit above is the simple, safe default. If volume demands batching, remember events buffered in memory are gone when the container stops — see Execution model for the container lifecycle.

The env.SECRETS binding is TypeScript-only, but secrets are also injected as plain environment variables into every function, so the same pattern works in any runtime: read the key from the environment (os.Getenv("LOG_SINK_KEY") in Go, os.environ in Python) and POST JSON to your sink.

Next Steps

Best Practices — error handling and outbound-call deadlines the emitter should respect
Limits — the 30 s default / 60 s max request budget your telemetry lives inside
Secrets — both access surfaces for the sink credential
CLI Reference — full flags for list, inspect, status, and revisions

CLI Reference

Source: https://developers.telnyx.com/docs/edge-compute/reference/cli.md

telnyx-edge is the command-line tool for Edge Compute: it scaffolds function projects, deploys them, and manages the resources they bind. This page covers every command in v0.2.5.

Command	What it does
auth	Log in via OAuth or API key; check or clear credentials
new-func	Scaffold a project and register the function server-side
ship	Upload, build, and deploy a function
list	List your functions with status and invoke URL
inspect	One function’s full details and actor bindings
status	CLI self-diagnostics: config, auth, connectivity
revisions	A function’s deploy history
rollback	Retarget traffic to a previous revision
secrets	Manage organization-scoped secrets
bindings	Manage the org-level Telnyx API credential
types	Generate `telnyx-env.d.ts` from the project manifest
storage	Manage KV namespaces and keys
actors	Manage account-scoped Stateful Actor types
reset-func	Return a failed function to the `created` state
delete-func	Delete a function permanently

Installation

The CLI ships as GitHub release binaries only — it is not on npm and there is no Homebrew formula. Assets are version-stamped; there is no un-versioned “latest” asset (releases/latest/download/... URLs return 404).

Platform	Asset
Linux amd64	`telnyx-edge-v0.2.5-linux-amd64.tar.gz`
Linux arm64	`telnyx-edge-v0.2.5-linux-arm64.tar.gz`
macOS arm64 (Apple silicon)	`telnyx-edge-v0.2.5-macos-arm64.tar.gz`
macOS amd64 (Intel)	`telnyx-edge-v0.2.5-macos-amd64.tar.gz`
Windows	`.zip` archives on the same release page

Each tarball extracts into a versioned directory containing the telnyx-edge binary:

VERSION=v0.2.5

curl -fsSL "https://github.com/team-telnyx/edge-compute/releases/download/${VERSION}/telnyx-edge-${VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv "telnyx-edge-${VERSION}-linux-amd64/telnyx-edge" /usr/local/bin/

telnyx-edge --version   # prints the installed version

For macOS, substitute macos-arm64 (Apple silicon) or macos-amd64 (Intel) in both lines. To update, download the new version’s asset and replace the binary the same way.

Global flags and configuration

Flag	Effect
`-h`, `--help`	Help for any command: `telnyx-edge --help`
`-v`, `--verbose`	Verbose logging — the first thing to try on an obscure failure
`--version`	Print the CLI version (root command only)

Credentials persist in ~/.telnyx-edge/config.toml. Two environment variables affect the binary itself: TELNYX_CONFIG_PATH relocates the config file, and TELNYX_NO_UPDATE_CHECK disables the release update check.

auth

telnyx-edge auth login                       # OAuth 2.0 in the browser
telnyx-edge auth api-key set "KEY..."        # persist a Telnyx API key instead
telnyx-edge auth status                      # who am I, and does the token work
telnyx-edge auth logout                      # clear stored tokens

login opens a browser for OAuth; api-key set writes the key to ~/.telnyx-edge/config.toml. Both end in the same place — subsequent commands read the stored credential. The CLI does not read a TELNYX_API_KEY environment variable. In CI, run telnyx-edge auth api-key set "$TELNYX_API_KEY" as a pipeline step — see CI/CD.

new-func

telnyx-edge new-func -l ts -n my-func
cd my-func

Flag	Description
`-l`, `--language`	Runtime — exactly one of `go`, `js`, `ts`, `python`, `quarkus`. Required unless `--from-dir` is given; the value is exact (`javascript` is rejected).
`-n`, `--name`	Function name. Becomes the directory name and part of the URL.
`--actor`	Scaffold a Stateful Actor (`telnyx.toml`) project — TypeScript only. See the Stateful Actors quick start.
`--from-dir`	Copy files from an existing directory instead of a language scaffold.

new-func does two things: it creates a project directory (the command fails if one with that name already exists), and it registers the function server-side — so it requires authentication, and the generated func.toml already contains the function’s UUID func_id. Rapid successive calls can hit HTTP 429 rate limits. What each scaffold contains:

Language	Files
`ts`	`func.toml`, `index.ts`, `package.json`, `tsconfig.json`
`js`	`func.toml`, `index.js`, `package.json`
`go`	`func.toml`, `handler.go`, `go.mod`
`python`	`func.toml`, `function/func.py`, `pyproject.toml`
`quarkus`	`func.toml`, `pom.xml`, `mvnw`, `.mvn/`, `src/main/java/functions/`

The entrypoint contract differs per language — see HTTP handler.

ship

telnyx-edge ship                       # deploy the function in the current directory
telnyx-edge ship --from-dir ../other   # or any relative, absolute, or ~/ path

Flag	Description
`-f`, `--from-dir`	Path to the function directory (default: current directory)
`-t`, `--timeout`	Deployment monitoring timeout as a Go duration (`2m`, `300s`; default `5m0s`)

ship uploads, builds, pushes, and deploys the function named by the directory’s func.toml. There is no environment flag — staging and production are separate functions. Umbrella projects (telnyx.toml) are bundled client-side before upload: the module graph rooted at main is compiled into a single file with esbuild (TypeScript/JavaScript only), and the manifest is included so the platform can deploy any [[actors]] it declares. On success, ship prints the live URL — stable across deploys:

📡 Your function is live at:
   https://my-func-myorg.telnyxcompute.com

The scheme is {func-name}-{org-nickname}.telnyxcompute.com — see Routes & Domains. Each successful ship also produces an immutable revision (revisions, rollback).

list

telnyx-edge list
telnyx-edge list --page 2 --page-size 50

Lists your functions — id, name, status, creation time, and invoke URL. Paginated: --page (default 1) and --page-size (default 25).

inspect

telnyx-edge inspect my-func   # accepts a name or an id (first column of 'list')

Shows one function’s status, invoke URL, and timestamps, plus the actor types it binds — each binding’s type, status, and owner/reference role.

status

telnyx-edge status

Self-diagnostics: config file existence, authentication status, and connectivity to https://api.telnyx.com. Run it first when any other command misbehaves.

revisions

telnyx-edge revisions list my-func

Lists the most recent revisions for a function, newest first, with each revision’s id, ship time, author, and deploy status; the revision currently serving traffic is marked. Every successful ship produces an immutable revision — see Versions & Rollback.

rollback

telnyx-edge rollback my-func a1b2c3d
# → Rollback of 'my-func' to revision a1b2c3d accepted; traffic is switching across clusters.

Instantly retargets traffic to an existing, immutable revision across all clusters — no rebuild, no re-upload. Only revisions that reached deploy_ok can be rolled back to; get ids from revisions list. Your source tree is untouched — the next ship deploys whatever is on disk, as a new revision.

secrets

Secrets are organization-scoped key-value pairs for sensitive data. The arguments are positional — there are no --name/--value flags:

telnyx-edge secrets add STRIPE_API_KEY "sk_live_abc123"
# → Secret 'STRIPE_API_KEY' added successfully

telnyx-edge secrets list      # keys only — values are never shown
telnyx-edge secrets delete OLD_API_KEY

add on an existing key overwrites it. Values are injected at deploy time, so ship each function that uses a changed secret. Functions read secrets two ways, and both are always true: every secret is injected as a plain environment variable into all functions in your organization, and TypeScript functions can additionally declare a [[secrets]] binding and read through the typed env.SECRETS.get(). See Secrets for both surfaces.

bindings

Manages the org-level Telnyx credential (one per organization) behind the Telnyx API binding. The per-function flow needs none of these commands — declaring [telnyx] in func.toml wires the binding automatically on ship.

telnyx-edge bindings create     # provision the org credential (one per organization)
telnyx-edge bindings get        # binding metadata
telnyx-edge bindings validate   # check the credential works
telnyx-edge bindings update     # regenerate — use if you suspect compromise
telnyx-edge bindings delete     # remove; functions lose automatic Telnyx API access

types

telnyx-edge types                  # writes telnyx-env.d.ts at the project root
telnyx-edge types -f ./my-func     # or point at another project directory

Generates TypeScript types for the env surface from your manifest (func.toml or telnyx.toml), folding every declared binding into one global Env interface:

Declaration	Generated type
`[telnyx]`	`env.` is the Telnyx client class from the `telnyx` npm package — `env..balance.retrieve()` type-checks
`[[secrets]]`	`env.SECRETS.get()` accepts the literal union of declared handles → `Promise`; a typo’d handle fails to compile
`[storage.kv.]`	`env.` is `KvNamespace` from `@telnyx/edge-runtime` — new in v0.2.3
`[storage.cloudstorage.]`	`env.` is `CloudStorageBucket` from `@telnyx/edge-runtime` — new in v0.2.4
`[[actors]]`	`env.` exposes the bound actor class’s public method signatures (umbrella `telnyx.toml` projects only)

Declarations only — no JavaScript, no runtime glue, no source edits. Re-run after changing any binding declaration. types generates a .d.ts consumed by tsc — it has no effect on js, go, python, or quarkus runtimes. Bindings on those runtimes are reached over REST instead; see Bindings.

storage

telnyx-edge storage kv create --name my-cache
telnyx-edge storage kv key put  user/123 "hello" --ttl 30s

Manages KV storage namespaces and keys: storage kv covers namespace create/list/get/delete, and storage kv key covers put/get/list/delete including server-side TTL and prefix listing. Full flags and examples live in the KV CLI reference.

actors

telnyx-edge actors list               # the account's registered actor types
telnyx-edge actors inspect Account    # one type, its attached functions, + live instance count
telnyx-edge actors instances Account  # list persisted instances (type/id pairs)
telnyx-edge actors delete Account     # delete an account-scoped type

Inspects and manages the Stateful Actor types registered to your account (account-scoped, keyed by type). inspect reports the actor type’s live instance count; instances lists the persisted instances (type/id pairs, e.g. Counter/alice). Output renders backend state — never inferred from local files.

reset-func

telnyx-edge reset-func broken-func

Tears down a failed function’s deployed resources and returns it to the created state — preserving its id, name, and config — so you can fix the code and ship again. Allowed only from a terminal failure state (build_failed, deploy_failed, delete_failed); a healthy function can’t be reset (use delete-func), and an in-progress operation must finish first.

delete-func

telnyx-edge delete-func my-old-func

Deletes a function by name. This cannot be undone — the function, its revisions, and its URL are gone.

Configuration — every func.toml / telnyx.toml key the CLI reads
CI/CD — install, authenticate, and ship from a pipeline
Versions & Rollback — how revisions and rollback behave
KV CLI — the full storage kv surface
Stateful Actors — the projects behind --actor and the actors command

Pricing

Source: https://developers.telnyx.com/docs/edge-compute/platform/pricing.md

Functions bill on two meters: requests (each HTTP request your function handles) and CPU time (metered in milliseconds). These are the only two meters — there is no charge for deploying, for the number of functions you keep, or for idle functions.

Functions

Resource	Free tier	Paid
Requests	3.6M/month	$0.21/million
CPU time	36M ms/month	$0.014/million ms

Storage

Storage is billed separately from function execution:

KV bills per operation and per GB-month stored — see KV Pricing.

Limits — execution, size, and rate limits
KV Pricing — operation and storage rates for KV

Limits

Source: https://developers.telnyx.com/docs/edge-compute/platform/limits.md

Limits are behavioral contracts: each one states what the platform enforces, what you see when you hit it, and what to do instead.

Execution Limits

Limit	Default	Maximum
Request timeout	30 seconds	60 seconds
Memory per container	256 MB	512 MB
Request body size	10 MB	10 MB
Response body size	10 MB	10 MB

Request timeout. A function must respond within the timeout or the request is terminated with a 504 Gateway Timeout. The timeout is not set in func.toml — there is no timeout_seconds field. Budget your own upstream calls below the platform limit (for example, a 25-second timeout on outbound requests) so you can return a real error instead of a 504. Memory. Each container has a fixed allocation. Exceed it and the container is terminated; the next request starts a fresh one (a cold start). Stream large payloads instead of buffering them, and don’t let in-memory caches grow unbounded — memory is per-container and disappears on restart anyway. For durable state, see Where state lives.

Function Limits

Limit	Value
Function code size	50 MB (compressed)
Environment variables per function	64
Environment variable name size	256 bytes
Environment variable value size	5 KB
Secrets per organization	100
Secret value size	10 KB

The code size limit includes dependencies after compression. If you hit it: remove unused dependencies, exclude development dependencies from the shipped directory, or split into multiple functions.

Network Limits

Limit	Value
Outbound connections per request	100
Outbound request timeout	Set by your code, bounded by the request timeout
DNS resolution timeout	5 seconds

The outbound connection count covers HTTP/HTTPS requests, database connections, and TCP sockets. Since a container serves many requests over its lifetime, open clients and connection pools once at module scope and reuse them across requests rather than reconnecting per invocation.

Rate Limits

Limit	Value
Deployments per hour	60
API requests per minute	1,000
Concurrent function invocations	No hard limit (auto-scales)

Function creation is also rate limited: telnyx-edge new-func registers the function server-side at scaffold time, and rapid successive calls return 429. Wait and retry. There is no hard cap on concurrent invocations — the platform scales containers with traffic. Each new container pays a cold start, so sharply spiky traffic sees higher tail latency.

Account Limits

Limit	Value
Functions per organization	100

Total requests and CPU time are usage-billed with a monthly free tier — see Pricing. Need higher limits? Contact support@telnyx.com.

KV Storage Limits

Limit	Value
Key length	256 characters — over returns `400`
Key characters	`a-z` `A-Z` `0-9` `-` `_` `/` `=` `.` (no colons)
Value size	1 MiB (1,048,576 bytes) — over returns `413`
TTL	Whole seconds, minimum 1

KV Best Practices is the authoritative KV limits page. For values over 1 MiB, store the object in Cloud Storage and keep a reference in KV.

When a Limit Is Exceeded

Error	Code	Meaning
Request Timeout	504	Function didn’t respond in time
Memory Exceeded	500	Container terminated due to memory
Payload Too Large	413	Request/response body exceeded limit
Rate Limited	429	Too many requests or deployments

Pricing — free tier and usage rates
Execution Model — container lifecycle and cold starts
KV Best Practices — full KV limits and guidance

Stateful Actors (Beta)

Stateful Actors

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors.md

A stateful actor is a single-threaded server that owns the state of one entity — one user, one cart, one call leg, one chat room. You write it as a TypeScript class; the platform runs one instance per name, routes every call for that name to that instance, runs your methods one at a time, and persists what you write. You never bind a socket, take a lock, or shard it.

import { StatefulActor } from "@telnyx/edge-runtime";

export class Account extends StatefulActor {
  async debit(amount: number): Promise<{ ok: boolean; balance: number }> {
    const balance = (await this.ctx.storage.get("balance")) ?? 0;
    if (balance < amount) return { ok: false, balance };   // check-then-act, no lock
    await this.ctx.storage.put("balance", balance - amount);
    return { ok: true, balance: balance - amount };
  }
}

That debit is a read-modify-write with no lock and no transaction. In a normal request handler that’s a race; here it isn’t — and that property is the whole product. How it works derives it from first principles, starting from a plain C server. Two words used precisely throughout these docs: the actor is the class you ship (Account); an instance is its per-name materialization (idFromName("acct_123") reaches the acct_123 instance of Account).

What the Runtime Guarantees

One instance per name — idFromName("acct_123") routes every call to a single owner; no two hosts run it at once.
One call at a time — single-threaded dispatch. No locks, no races inside an instance.
Durable before reply — a method’s result isn’t returned until the writes it made are persisted.
Memory is a cache — only what you write to storage survives eviction or restart.

Execution model states each precisely; How it works derives them from a plain C server. Scaffold, deploy, and curl an actor. The C-vs-actor derivation from first principles. The four guarantees, stated precisely. Where instances run; what survives a restart. Naming and routing instances. The two-export shape. Reach one actor from many functions. And when to reach for something else. The full surface. Scheduled work from inside an actor. Terminate a live socket on the actor — each frame is a serialized turn.

Bindings — how bindings resolve on env
KV — globally distributed key-value storage
Execution Model — function lifecycle and concurrency

Stateful Actors Quick Start

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/quick-start.md

Ship an Account actor end-to-end: scaffold, write the class, deploy, and curl it. Each account name is its own actor instance — alice and bob are isolated, each with their own balance, all persisted. Roughly 10 minutes.

What You’ll Build

A function with routes that all share a single durable Account actor type — but each account name is its own isolated instance:

POST /accounts/:id/deposit   { "amount": 100 }  → { account, balance }
POST /accounts/:id/debit     { "amount": 30 }   → { account, ok, balance }
GET  /accounts/:id/balance                       → { account, balance }
GET  /health/{liveness,readiness}                → "ok"

A debit never overdraws, and a committed debit is never lost.

Why an Account

An Account exercises the three properties a Stateful Actor gives you:

Per-instance isolation — alice and bob are separate actor instances with their own balance.
Single-threaded dispatch — concurrent debits on the same account serialize automatically. No lock, no race: two debits can’t both pass the balance check.
Persistence — the balance survives across requests; it’s durable and reloaded when the actor is next invoked.

Prerequisites

The telnyx-edge CLI, installed and authenticated — a release with Stateful Actor deploy support. v0.2.2 and earlier cannot ship an actor project (new-func --actor appears to work, but ship fails); upgrade from the releases page.
A Telnyx API key.
Node.js (for npm).

1. Authenticate

telnyx-edge auth api-key set
telnyx-edge auth status

2. Scaffold the Actor Project

telnyx-edge new-func --actor --name=account
cd account
npm install

This writes an umbrella telnyx.toml (with a [[actors]] block), a sample actor class, a fetch handler, and registers the function (writes a func_id into telnyx.toml). npm install pulls in @telnyx/edge-runtime.

3. Write the Account Actor

Replace the scaffolded actor class with src/account.ts. It holds one value — the balance — in this.ctx.storage:

import { StatefulActor } from "@telnyx/edge-runtime";

export class Account extends StatefulActor {
  /** Add funds. Returns the new balance. */
  async deposit(amount: number): Promise<{ balance: number }> {
    const balance = (await this.ctx.storage.get("balance")) ?? 0;
    const next = balance + amount;
    await this.ctx.storage.put("balance", next);
    return { balance: next };
  }

  /** Subtract funds if sufficient. Atomic — single-threaded dispatch means
   *  two debits on the same account can't both pass the check. */
  async debit(amount: number): Promise<{ ok: boolean; balance: number }> {
    const balance = (await this.ctx.storage.get("balance")) ?? 0;
    if (balance < amount) return { ok: false, balance }; // insufficient funds
    const next = balance - amount;
    await this.ctx.storage.put("balance", next);
    return { ok: true, balance: next };
  }

  /** Read the current balance. */
  async balance(): Promise<{ balance: number }> {
    return { balance: (await this.ctx.storage.get("balance")) ?? 0 };
  }
}

4. Write the Fetch Handler

Replace src/index.ts with a handler that routes HTTP to actor method calls. It re-exports the actor class (so it ships with the bundle) and calls it through the ACCOUNT binding on env:

// Re-export the actor class from the entry point so it is bundled and shipped
// with the function. The exported class name must equal the [[actors]] type.
export { Account } from "./account";
import type { Account } from "./account";

import {
  type ActorNamespace,
  type ActorStub,
  type IdFromNameOptions,
} from "@telnyx/edge-runtime";

type AccountStub = ActorStub & Pick;
interface AccountNamespace extends ActorNamespace {
  idFromName(name: string, options?: IdFromNameOptions): AccountStub;
}
interface Env {
  ACCOUNT: AccountNamespace;
}

export default {
  async fetch(req: Request, env: Env): Promise {
    const url = new URL(req.url);

    if (url.pathname === "/health/liveness") return new Response("ok");
    if (url.pathname === "/health/readiness") return new Response("ok");

    const m = url.pathname.match(/^\/accounts\/([^/]+)\/(deposit|debit|balance)$/);
    if (!m) return new Response("not found", { status: 404 });

    const id = m[1]!;
    const action = m[2]!;
    const stub = env.ACCOUNT.idFromName(id);

    if (action === "deposit" && req.method === "POST") {
      const body = (await req.json().catch(() => ({}))) as { amount?: number };
      if (typeof body.amount !== "number")
        return Response.json({ error: "amount (number) required" }, { status: 400 });
      const result = await stub.deposit(body.amount);
      return Response.json({ account: id, ...result });
    }

    if (action === "debit" && req.method === "POST") {
      const body = (await req.json().catch(() => ({}))) as { amount?: number };
      if (typeof body.amount !== "number")
        return Response.json({ error: "amount (number) required" }, { status: 400 });
      const result = await stub.debit(body.amount);
      return Response.json({ account: id, ...result });
    }

    if (action === "balance" && req.method === "GET") {
      const result = await stub.balance();
      return Response.json({ account: id, ...result });
    }

    return new Response("not found", { status: 404 });
  },
};

5. Update `telnyx.toml`

Point the [[actors]] binding at your class. The scaffold generated a sample binding; change it to ACCOUNT → Account:

name = "account"
main = "src/index.ts"
compatibility_date = "2026-05-01"

[[actors]]
binding = "ACCOUNT"   # the property on env — your handle
type    = "Account"   # the class to instantiate per account name

[edge_compute]
func_id = "..."       # created by new-func; leave as-is
func_name = "account"

6. Deploy

telnyx-edge ship

ship bundles the project, uploads it, and monitors the deploy — wait for ✅ Func 'account' is now deployed! (in telnyx-edge list, the function’s status becomes deploy_ok).

7. Hit the URL

ship prints a URL like account-.telnyxcompute.com. The function may take a moment to come up — poll the health endpoint until it returns 200:

B=https://account-.telnyxcompute.com

# wait for it to come up
curl -sS --retry 30 --retry-delay 5 --retry-connrefused "$B/health/liveness"

Now exercise it — two accounts, no overdraw, isolation, persistence:

# alice deposits 100, then debits 30
curl -sS -X POST $B/accounts/alice/deposit -H 'content-type: application/json' -d '{"amount":100}'
# → {"account":"alice","balance":100}
curl -sS -X POST $B/accounts/alice/debit   -H 'content-type: application/json' -d '{"amount":30}'
# → {"account":"alice","ok":true,"balance":70}

# an overdraw is rejected — balance unchanged
curl -sS -X POST $B/accounts/alice/debit   -H 'content-type: application/json' -d '{"amount":1000}'
# → {"account":"alice","ok":false,"balance":70}

# bob is a separate instance with its own balance
curl -sS -X POST $B/accounts/bob/deposit   -H 'content-type: application/json' -d '{"amount":5}'
# → {"account":"bob","balance":5}

# isolation + persistence: alice is still 70, bob is 5
curl -sS $B/accounts/alice/balance   # → {"account":"alice","balance":70}
curl -sS $B/accounts/bob/balance     # → {"account":"bob","balance":5}

You should see:

alice ends at 70 (100 − 30; the 1000 debit was rejected)
bob is independent at 5
alice is unchanged by bob’s activity (isolation), and survives across requests (persistence)

Next Steps

Shared Actors — add a second function that reads/writes the same Account through a different binding
Runtime API — StatefulActor, ctx, storage, alarms
Alarms — schedule deferred work from inside an actor method

How It Works

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/concepts/how-it-works.md

Take a concrete problem: keep a balance per account, reachable over HTTP, correct when requests overlap, and intact across restarts. A debit must never overdraw, and a committed debit must never be lost. Below is what that actually requires, from first principles, and how a stateful actor hands you the same thing.

How You’d Build This, from First Principles

Strip it to the metal. One process serves every account — a, b, c, x, y, … — holding them all in an in-memory map and handling a request for whichever one comes in. Two things make each debit correct: a per-account lock, so two debits on the same account can’t interleave (while debits on different accounts still run in parallel), and a write-ahead log + fsync, so a committed debit is on disk before you reply.

struct account {
    int64_t         balance;
    pthread_mutex_t lock;     // serializes debits on THIS account; other accounts run in parallel
};
// one process, every account: a map of account_id -> struct account *
struct account *lookup_or_create(const char *acct_id);

Durability is append-to-log then fsync — you don’t acknowledge the debit until the bytes are on disk:

void persist_data(const char *acct_id, int64_t balance) {
    dprintf(wal_fd, "%s %lld\n", acct_id, (long long)balance);  // append one record to the log
    fsync(wal_fd);                                              // the durability boundary: on disk before we return
}

A request names an account; the process looks it up and serves it. Lock that account, check-and-decrement, log, fsync, unlock:

// One process, any account. Error handling elided.
int debit(const char *acct_id, int64_t amount, int64_t *out) {
    struct account *a = lookup_or_create(acct_id);  // a, b, c, x, y ... all live in this process

    pthread_mutex_lock(&a->lock);              // serialize debits on THIS account
    if (a->balance < amount) {
        pthread_mutex_unlock(&a->lock);
        return -EAGAIN;                         // insufficient funds
    }
    a->balance -= amount;
    persist_data(acct_id, a->balance);          // append a record + fsync: durable before we return

    *out = a->balance;
    pthread_mutex_unlock(&a->lock);
    return 0;
}

Two primitives do all the work: the lock is the serialization point, and fsync before you reply is durability. Everything else follows:

one process owns it all — the map, the per-account locks, and the log are shared by every account a…y;
durability is the log: a debit is committed once its record is fsync’d, so a crash loses only what was never acked;
recovery is not replaying an ever-growing log from zero — that gets slower forever. You periodically write a snapshot of all balances and keep only the log records since it; on restart you load the snapshot and replay that short tail. (Postgres’ checkpoint + WAL, SQLite’s WAL mode, and Redis’ RDB + AOF all do exactly this.) The on-disk snapshot + log is the truth; memory is a cache;
to grow past one process you shard accounts across processes and machines, routing each account to the one that owns it — and this is where most people stop hand-rolling and reach for a database, which is exactly this machine (sharded, replicated, snapshot + write-ahead log) run by someone else. Postgres’ COMMIT is what persist_data does, its checkpoint is your snapshot, and SELECT … FOR UPDATE is the lock.

You can build all of this. The work isn’t any single line — it’s that you own the lock discipline on every path, the log format, the snapshots, the recovery, the sharding, and the restarts, forever.

The Same Thing as a Stateful Actor

import { StatefulActor } from "@telnyx/edge-runtime";

export class Account extends StatefulActor {
  async debit(amount: number): Promise<{ ok: boolean; balance: number }> {
    const balance = (await this.ctx.storage.get("balance")) ?? 0;
    if (balance < amount) return { ok: false, balance };   // check-then-act, no lock
    await this.ctx.storage.put("balance", balance - amount);
    return { ok: true, balance: balance - amount };
  }
}

The class is only the logic half. In the C version, debit(acct_id, …) did the lookup itself (lookup_or_create) and the logic. With an actor that lookup moves to the caller: a normal function parses the request, names the account with idFromName, and calls the method — which now takes only amount and never has to find its own state.

import { type ActorNamespace, type ActorStub } from "@telnyx/edge-runtime";
import { Account } from "./account";
export { Account };

type AccountStub = ActorStub & Pick;
interface AccountNamespace extends ActorNamespace {
  idFromName(name: string): AccountStub;
}
interface Env { ACCOUNT: AccountNamespace }

export default {
  async fetch(req: Request, env: Env): Promise {
    const acct = new URL(req.url).pathname.slice(1);     // /acct_123 — the account name
    const { amount } = (await req.json()) as { amount: number };
    const result = await env.ACCOUNT.idFromName(acct).debit(amount);  // route by name, then call
    return Response.json(result);
  },
};

idFromName(acct) is the actor-world lookup_or_create — instead of finding a struct in this process’s map, it routes to the one instance that owns that account, anywhere (the “Reaching one account” row below). Same check-and-decrement, same durability requirement — but no pthread_mutex, no fsync, no log, no snapshots, no shard map. The two primitives are still there; the runtime provides them. Here’s the mapping, mechanism by mechanism:

Mechanism (first principles)	Hand-rolled in C	Stateful actor
Serialization point	a `pthread_mutex` per account, held across the change	one thread per name — the lock you can’t forget, because there is none
Durable before you reply	`persist_data` — append + `fsync` — then ack	method returns ⇒ writes flushed (flush-before-ack)
Truth vs cache	the snapshot + log on disk; the in-memory map is a cache	`ctx.storage`; instance fields are a cache, gone on restart
Reaching one account	a map lookup in-process; a shard map + router once you outgrow one process	`idFromName(name)` routes to the one owner
Parallelism across accounts	per-account locks in one multi-threaded process	a separate instance per name — each its own thread and `storage`
Restart recovery	load the snapshot, replay the log tail	runtime restarts the instance; `storage` is already durable
Scheduling	a `timerfd` + a timer wheel	`ctx.storage.setAlarm` + an `alarm()` handler

The runtime takes the one process that multiplexed a, b, c, x, y and splits it: each account id becomes its own instance. idFromName("a") and idFromName("b") are two different instances, on two different threads, each with its own storage — debits on a serialize, debits on a and b run in parallel, and there is no shared map, per-account lock, or single log to own. A stateful actor is that machine — a single-threaded server with durable, flush-before-ack storage, one per account — that the platform shards, routes, and restarts for you. You write the body of debit; the runtime is the lock, the durability, the recovery, and the router. The four guarantees the runtime makes from this mapping are stated precisely in Execution model.

Next Steps

Execution model — the four guarantees, stated precisely
Lifecycle & placement — where an instance runs, and what survives a restart
Addressing — naming and routing instances
Project structure — the two-export shape

Execution Model

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/concepts/execution-model.md

The runtime makes four guarantees. Each is the managed form of a mechanism you’d otherwise build by hand — the C server and mapping table in How it works show where each one comes from. Stated precisely: 1. Exactly one instance per name. idFromName("acct_123") routes every call for that name to one owner — the shard map and router you’d otherwise build by hand, done for you. No two hosts run account acct_123 at once, so the instance is the source of truth for that account. 2. One call at a time — no concurrency inside an instance. This is the per-account pthread_mutex, except you don’t write it and can’t forget it. One thread per instance runs each method to completion before the next starts. await yields the thread, but the next call still won’t start until your method returns. The C debit is correct because it holds the lock across the change; the actor debit is correct because two debits on one account never run at the same time. 3. Writes are durable before the caller sees a result. This is write() + fsync() before you reply. When your method returns, the runtime holds the response until every write you issued has been flushed — the caller can’t observe a result built on an unflushed write. (If a write rejects after the method returns, the call fails with ActorOutputGateError instead of returning success.) 4. Only persisted state survives; memory is a cache. This is “the on-disk snapshot + log is the truth; the in-memory map is a cache.” An instance can be evicted or restarted between any two calls — a deploy, idle eviction, host failure — and instance fields (this.x) vanish while ctx.storage does not. The runtime does the snapshotting and recovery; you just read from storage. Treat memory exactly like a process that can be SIGKILLed at any instant: only what you flushed to storage is real.

Next Steps

How it works — the C-vs-actor derivation behind these guarantees
Lifecycle & placement — how eviction and restart play out (guarantee 4)
When to use — the throughput limits these guarantees imply

Lifecycle & Placement

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/concepts/lifecycle.md

A stateful actor instance is activated on demand, kept in memory while it’s busy, evicted when idle, and can be restarted or relocated at any time. You don’t manage any of this — but you design around it, because only what you write to storage survives.

Where it Runs

An instance is placed on first touch — the first method call to a name brings it up. After that you address it by name, never by location; the platform routes every call to wherever the instance currently lives. (idFromName accepts a locationHint option, reserved for regional placement — see Actor Namespace.)

Activation and Eviction

Activated on demand. Naming an instance is cheap; the first method call to a name brings the instance up and routes the call to it.
Kept warm while busy, evicted when idle. Between calls, an idle instance may be removed from memory to free resources, then re-activated on the next call.
Restarted on deploy or host failure. A new code version or a host issue tears the instance down and re-creates it.

What Survives a Restart

In-memory state — instance fields like this.x — is a cache. It vanishes on eviction, restart, or relocation. Your actor’s storage is the truth: it is durable and reloaded when the instance next activates. Treat memory exactly like a process that can be SIGKILLed at any instant — only what you flushed to storage is real. (This is guarantee 4 in Execution model.) A common pattern is to load from storage once on activation and cache the result in memory; just never assume the cache is still there.

Next Steps

How it works — the execution model and its guarantees
Addressing — naming and routing instances
Runtime API — ctx.storage, blockConcurrencyWhile

Addressing

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/concepts/addressing.md

env. is your handle to an actor class. You name an instance, get a stub, and call methods on it.

Two Ways to Name an Instance

env.ACCOUNT.idFromName("acct_123") // deterministic — your shard key; same name, same instance
env.ACCOUNT.newUniqueId()          // random — mints a fresh, unguessable identity

idFromName(name) is deterministic: the same name always lands on the same instance, from anywhere. This is the common case — pick a stable identity for the entity and let the platform route to its state.
newUniqueId() mints a fresh, unguessable instance; you store the id (stub.id) yourself. It currently fails at call time on the platform (a known runtime issue — see Actor Namespace); until it’s fixed, mint an identity yourself and pass it to idFromName.

Choosing a Name

The name is your shard key — choose the entity’s natural identity: a caller’s E.164 number, a user or account id, a room id, or a composite key (tenant:room). Same name → same single-threaded instance → coherent state for that entity. Spreading load means choosing names that spread across entities; a single hot name is one single-threaded bottleneck (see When to use).

Calling the Stub

Both calls return a stub. Calling a method on the stub is an RPC to that one instance: the call is queued there, your method runs, the value comes back.

Next Steps

How it works — why one-instance-per-name gives coherent state
Project structure — declaring the binding in telnyx.toml
Runtime API — ActorNamespace and ActorStub

Overview

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference.md

The types in this reference are exported from @telnyx/edge-runtime (TypeScript). The Stateful Actor surface at a glance — follow a link for the full page:

Surface	Where it lives	What it’s for
`StatefulActor`	`@telnyx/edge-runtime`	Base class you extend. Holds `this.ctx` and `this.env`.
`ActorContext`	`this.ctx` (runtime-injected)	Per-instance identity, storage, single alarm, one-shot init.
`ActorStorage`	`this.ctx.storage`	Per-key persistent storage.
`ActorNamespace`	`env.`	The handle from your function. Returns stubs you call methods on.
`ActorStub`	from `idFromName` / `newUniqueId`	Per-name handle; an RPC to one instance.
Alarms	`ctx.storage` + `alarm()`	Single per-actor alarm; at-least-once delivery.
Configuration	`telnyx.toml` `[[actors]]`	Declaring the actor binding.
Errors	`@telnyx/edge-runtime`	`BlockConcurrencyTimeoutError`, `ActorOutputGateError`, timeout and codec errors.

Bindings — how bindings resolve on env
KV — globally distributed key-value storage
Execution Model — function lifecycle and concurrency

Base Class

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/base.md

StatefulActor is the base class you extend. Subclass it, declare async methods, and they become RPC-callable from a stub. It holds this.ctx (see Actor Context) and this.env (your bindings).

import { StatefulActor } from "@telnyx/edge-runtime";

export class Account extends StatefulActor {
  async debit(amount: number): Promise<{ ok: boolean; balance: number }> {
    const balance = (await this.ctx.storage.get("balance")) ?? 0;
    if (balance < amount) return { ok: false, balance };
    await this.ctx.storage.put("balance", balance - amount);
    return { ok: true, balance: balance - amount };
  }
}

Construction

You don’t construct actors yourself — the runtime does. The base constructor wires this.ctx and this.env, so a subclass that doesn’t need init logic can omit its constructor entirely.

class MyActor extends StatefulActor {
  // no constructor needed — this.ctx and this.env are wired by the base
}

If you do need one-shot init (preload state, set up an initial alarm), override the constructor and call ctx.blockConcurrencyWhile — see Actor Context.

Dispatch Rules

Public methods are RPC-callable from a stub — declare them async (every stub call is a Promise on the caller’s side regardless).
Methods whose names start with _ are internal helpers and are not RPC-exposed — the runtime rejects the call.
The _ prefix is the only opt-out. TypeScript’s private keyword is erased at runtime and does not stop remote calls; name internal helpers with a leading _.
fetch(req), alarm(info), webSocket(ws, req), the constructor, and methods defined on StatefulActor itself (not your subclass) are special and not auto-RPC.
Methods have a wall-clock budget (30s by default). A call that exceeds it fails with ActorMethodTimeoutError — see Errors.

`alarm(alarmInfo)`

Optional alarm handler. Override to handle scheduled work. The base implementation is a no-op.

async alarm(info: AlarmInfo): Promise {
  // at-least-once delivery — be idempotent
  // info.retryCount is 0 on first delivery; info.isRetry is true on retries
}

See Alarms for the delivery contract and retry policy.

`fetch(req)`

Optional HTTP-style entry. The base default returns 404. Override if you want callers to reach the actor over a raw Request instead of RPC methods:

async fetch(req: Request): Promise {
  return new Response("hello from " + this.ctx.id);
}

Callable from a binding as env.BINDING.idFromName(name).fetch(req).

`webSocket(ws, req)`

Optional WebSocket entry. Unlike alarm() and fetch(), there is no default implementation — declaring the method is the opt-in. An actor that doesn’t declare webSocket() has no socket behavior at all, and an upgrade routed at it is closed with code 1011 (reason actor has no webSocket handler).

import { StatefulActor } from "@telnyx/edge-runtime";
import type { WebSocket } from "ws";

export class Room extends StatefulActor {
  async webSocket(ws: WebSocket, req: Request): Promise {
    const user = req.headers.get("x-user") ?? "anonymous";

    ws.on("message", async (data, isBinary) => {
      if (isBinary) return;
      // messages dispatch one at a time — this read-modify-write never races
      const seq = ((await this.ctx.storage.get("seq")) ?? 0) + 1;
      await this.ctx.storage.put("seq", seq);
      ws.send(JSON.stringify({ echo: String(data), seq, user }));
    });
  }
}

Called once per accepted connection, with the live socket and the handshake Request. req is the request your function’s front door forwarded: the URL plus application headers, with transport and handshake headers stripped — see WebSockets for the contract. Client-sent app headers pass through too, so trust only headers your front door explicitly set or overwrote — the front door must overwrite or strip anything auth-bearing (like x-user above) before forwarding.
ws is a Node ws socket (import type { WebSocket } from "ws"): ws.on("message", (data, isBinary) => ...), ws.send(data), ws.close(code, reason). There is no WebSocketPair/accept() shape.
Register your listeners before webSocket() returns. Frames that arrive before webSocket() returns — including any the client sent immediately after the handshake — are buffered and replayed in order once it returns; nothing drops.
Socket events share the instance’s single-threaded dispatch. message, close, and error handlers run one at a time, serialized with RPC methods and alarms, each under the method wall-clock budget (30s by default). A message handler that throws or exceeds the budget closes the socket with code 1011.

Connections reach the actor through your function’s fetch front door: check the Upgrade header, authenticate, then forward with env.BINDING.idFromName(name).fetch(...). See WebSockets for the front door, connection lifetime, close codes, and delivery semantics.

WebSockets — the full connection contract behind webSocket()
Actor Context — this.ctx: identity, storage, init
Actor Storage — this.ctx.storage
Configuration — the telnyx.toml actor block

Actor Context

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/context.md

this.ctx (an ActorContext) holds the instance’s identity, per-key storage, single alarm, one-shot init, and the instance’s live WebSocket connections.

interface ActorContext {
  readonly id: string;             // the name you chose with idFromName(name)
  readonly storage: ActorStorage;  // see Actor Storage
  blockConcurrencyWhile(fn: () => Promise): Promise;
  setAlarm(when: number): Promise;  // alias for ctx.storage.setAlarm(when)
  count(): number;                 // live WebSockets on this instance
  broadcast(data: string | ArrayBuffer | ArrayBufferView): number;  // returns sent count
}

`ctx.id`

The customer-supplied name for this actor — opaque string. You chose it via env..idFromName(name). Common patterns: caller E.164, CRM user id, email, or a composite key.

`ctx.blockConcurrencyWhile(fn)`

One-shot init primitive. Use it inside a subclass constructor to gate all other calls until init finishes. 30s budget — a callback that exceeds it fails init (BlockConcurrencyTimeoutError), and the activation is torn down and retried on the next call.

class MyActor extends StatefulActor {
  constructor(ctx: ActorContext, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      // preload state, set up initial alarm, etc.
      // every other method call to this instance waits until this resolves
    });
  }
}

`ctx.setAlarm(when)`

Top-level alias for ctx.storage.setAlarm(when). when is ms since epoch. See Alarms.

`ctx.count()`

The number of WebSocket connections open on this instance right now. Synchronous — no await. Scoped to the instance: sockets on other names of the same actor class are never counted, and a socket never carries over between names. Callable from any handler — a socket message handler, an RPC method, or the alarm handler.

`ctx.broadcast(data)`

Send one frame to every WebSocket open on this instance; returns the number of sockets the frame was sent to. A string is sent as a text frame; an ArrayBuffer or ArrayBufferView as a binary frame. Scoped to the instance, like count() — a broadcast never reaches another name’s sockets. Like ws.send(), the write happens immediately; it is not held until the turn’s storage writes commit. Callable from any handler. Calling it from alarm() is the server-initiated push pattern — the actor sends with no inbound frame prompting it:

async alarm(): Promise {
  this.ctx.broadcast(JSON.stringify({ type: "tick", at: Date.now() }));
}

See WebSockets for how sockets reach the actor in the first place.

Actor Storage — ctx.storage
Base Class — where this.ctx comes from
Alarms — the alarm contract
WebSockets — the connection contract behind count() and broadcast()

Actor Storage

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/storage.md

this.ctx.storage (an ActorStorage) is the actor’s per-key persistent storage. A turn that returns successfully is persisted — all writes made during the turn (put/delete/transaction/sql.exec/setAlarm) commit atomically at end-of-turn; a turn that throws commits nothing.

interface ActorStorage {
  get(key: string): Promise;
  put(key: string, value: T): Promise;
  delete(key: string): Promise;            // true iff the key existed
  list(options?: ListOptions): Promise>;
  deleteAll(): Promise;                        // atomic clear of all keys; does NOT clear a pending alarm
  transaction(fn: (txn: StorageTransaction) => Promise): Promise;

  readonly sql: SqlStorage;                          // per-actor embedded SQLite (synchronous)
  transactionSync(fn: () => T): T;                // atomic SQL transaction (synchronous)

  // Alarm API (mirrors ctx.setAlarm)
  // Available in local development; prod support is pending.
  setAlarm(when: number): Promise;
  getAlarm(): Promise;
  deleteAlarm(): Promise;
}

Key behaviors:

Lazy per get — state is not preloaded on activation. Call get when you need it.
Read-your-writes — reads always reflect prior writes from the same actor.
Per-actor method serialization — calls to one actor instance are dispatched one at a time, giving you effective ACID at the actor level.
Values round-trip through a codec. JSON natives plus Date, Map, Set, typed arrays, ArrayBuffer, BigInt, and RegExp come back as what you stored. Unstorable values — functions, class instances, circular structures, promises, streams — are rejected with a CodecError at the write.
Keys starting with __telnyx_ are reserved for the runtime’s own bookkeeping — writes to them are rejected.

`list(options)`

Lexicographic key order; reverse: true flips it. Returns a Map to preserve ordering.

interface ListOptions {
  prefix?: string;        // filter to keys starting with this string
  start?: string;         // inclusive
  startAfter?: string;    // exclusive
  end?: string;           // exclusive
  reverse?: boolean;
  limit?: number;         // default 128, max 1000 — a larger limit is rejected
}

`transaction(fn)`

Atomic batch. fn receives a StorageTransaction with the same get/put/delete/list surface.

await this.ctx.storage.transaction(async (txn) => {
  const v = (await txn.get("count")) ?? 0;
  await txn.put("count", v + 1);
  await txn.put("updated_at", Date.now());
});

If fn throws, the buffered writes are discarded — and the enclosing method call fails with ActorOutputGateError, even if your code catches the rejection. Only the transaction’s own writes are undone: writes you make after catching the rejection still commit, but the caller sees the error instead of your return value. A thrown transaction is not a control-flow tool for “try the write, continue on failure”.

`sql`

ctx.storage.sql is a private embedded SQLite database for this actor — a separate, synchronous store beside the key/value surface above. See SQL storage for the exec / cursor contract, types, transactions, limits, and durability.

`transactionSync(fn)`

Atomic SQL transaction: runs fn synchronously, commits its sql.exec writes when it returns (passing the return value through), rolls all of them back if it throws. fn must not be async — an async callback throws SqlAsyncTransactionError and commits nothing. This is the only transaction API for SQL: exec() rejects raw BEGIN / COMMIT / ROLLBACK / SAVEPOINT with SqlTransactionControlError. Unlike a thrown transaction(fn), a thrown transactionSync does not poison the turn: catch it and the method call completes normally.

Key-Value storage — the get/put/list guide
SQL storage — the ctx.storage.sql guide
Actor Context — ctx.storage lives here
Alarms — the setAlarm / getAlarm / deleteAlarm contract

Actor Namespace

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/namespace.md

env. is an ActorNamespace — the handle on env that your function calls into. It’s declared in telnyx.toml:

[[actors]]
binding = "ACCOUNT"    # env.ACCOUNT
type    = "Account"    # the class to instantiate per name

interface ActorNamespace {
  idFromName(name: string, options?: IdFromNameOptions): ActorStub;
  newUniqueId(options?: IdFromNameOptions): ActorStub;
}

interface IdFromNameOptions {
  locationHint?: LocationHint;     // "us-east" | "us-west" | "eu" | "apac" | (string & {})
}

`idFromName(name, options?)`

Deterministic — the same name always lands on the same actor instance. This is the most common call: pick a stable identity (caller E.164, CRM id, room id) and let the platform route to the right state. locationHint is a placement hint, relevant on first touch only — an actor materializes once, so a hint on a later call can’t move it. The platform may ignore the hint entirely (today it does — the option is accepted and reserved for regional placement). Abstract region codes (the taxonomy can evolve without breaking your code).

`newUniqueId(options?)`

Random — a fresh, unguessable instance. Use when you want the runtime to mint the identity for you (e.g. a one-shot job actor). The id is generated client-side; keep it (via stub.id) if you’ll need to reach the instance again. newUniqueId currently fails at call time on the platform (a known runtime issue). Until it’s fixed, mint an identity yourself and pass it to idFromName. Both return an Actor Stub. Method dispatch on the stub is provided by the runtime via a Proxy; in TypeScript, run telnyx-edge types to type env. against your class’s public method shape, or hand-roll the narrowing — the Actor Stub page shows both.

Actor Stub — what idFromName / newUniqueId return
Configuration — declaring the binding
Addressing — naming and routing

Actor Stub

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/stub.md

An ActorStub is the client handle returned by idFromName / newUniqueId. Calling a method on it is an RPC to that one actor instance.

interface ActorStub {
  readonly id: string;                       // the name passed to idFromName
  fetch(req: Request): Promise;    // HTTP-style entry (see Base Class fetch)
  // + your subclass's public methods — typed via `telnyx-edge types` or by hand, below
}

telnyx-edge types generates the narrowing for every [[actors]] binding in telnyx.toml — a telnyx-env.d.ts that types env. against your class’s public method shape. To hand-roll it instead (also the path for a shared-actor reference, which ships no local class for codegen to read):

import { type ActorNamespace, type ActorStub, type IdFromNameOptions } from "@telnyx/edge-runtime";

type AccountStub = ActorStub & Pick;

interface AccountNamespace extends ActorNamespace {
  idFromName(name: string, options?: IdFromNameOptions): AccountStub;
}

interface Env { ACCOUNT: AccountNamespace }

Actor Namespace — produces stubs
Base Class — the fetch handler a stub can call

Actor Alarms

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/alarms.md

Every Stateful Actor has a single per-instance alarm — a one-shot timer you can set, replace, read, or clear from inside any method. When the alarm fires, the runtime calls the actor’s alarm(alarmInfo) handler. Alarms are the way to do deferred work without an external scheduler.

What	How
Set or replace the alarm	`await this.ctx.storage.setAlarm(when)` — `when` is ms since epoch
Read the scheduled time	`await this.ctx.storage.getAlarm()` → `number \| null`
Clear the alarm	`await this.ctx.storage.deleteAlarm()`
Top-level alias	`await this.ctx.setAlarm(when)` (mirrors `storage.setAlarm`)
Handle the fire	override `async alarm(info: AlarmInfo)` on your subclass

There is one alarm per actor instance, not per method or per key. Setting it again replaces the previous time.

Set and Handle

import { StatefulActor, type AlarmInfo } from "@telnyx/edge-runtime";

export class Session extends StatefulActor {
  // Called when a session is touched — push the timeout out by 5 minutes.
  async touch() {
    await this.ctx.storage.put("last_seen", Date.now());
    await this.ctx.storage.setAlarm(Date.now() + 5 * 60_000);
  }

  // Fires once when the alarm goes off.
  async alarm(info: AlarmInfo): Promise {
    const lastSeen = (await this.ctx.storage.get("last_seen")) ?? 0;
    if (Date.now() - lastSeen > 5 * 60_000) {
      // session actually idle — clean up
      await this.ctx.storage.deleteAll();
    }
  }
}

The handler is just another method call on the actor — it inherits the same single-threaded dispatch guarantee as any other method. You don’t need a lock around the state the alarm touches.

Delivery Contract

AlarmInfo:

interface AlarmInfo {
  retryCount: number;   // 0 on first delivery; increments on each retry
  isRetry: boolean;     // true when retryCount > 0
}

At-least-once delivery. Plan for the handler to run more than once for the same scheduled time. Make writes idempotent — re-check state in storage before applying effects (as the Session example above does), or record a done-marker keyed by the scheduled time.
A failed run is redelivered 3 times, about a second apart. If the handler throws (or exceeds its time budget), the platform re-fires it with retryCount incremented — 4 attempts total, then the alarm is deleted (getAlarm() returns null). There is no signal when that happens.
A failing handler loses its alarm — don’t use throw as your retry mechanism. Three retries a second apart won’t outlast a real outage. If the deferred work must happen, make the handler tolerate its own errors: catch, record, and re-arm with setAlarm at a backoff you choose.
Use info.isRetry to branch. On retry, log it, treat the work as best-effort, or skip already-completed steps.

async alarm(info: AlarmInfo): Promise {
  if (info.isRetry) {
    // redelivery after a failed run — be extra careful about double-applies
  }
  // re-check state in storage before applying effects, then do the work
}

Patterns

TTL / expiry

Set the alarm when you create the row; on fire, check the row is still expired and delete it. If the row was touched since, reset the alarm instead.

Retry backoff

If your method kicks off a flaky external call, set an alarm to retry later; on fire, attempt again and either succeed or set a new alarm with a longer backoff.

Session timeout

See Session.touch above — every interaction pushes the alarm out by the idle window; the alarm only fires if no one touches the session in time.

Coalesced drain

Because there’s only one alarm per instance, you can use it as a “flush trigger”: set it on the first write, and when it fires, drain the queue and clear it. Subsequent writes during the window just append to the queue.

Limits

One alarm per actor instance. If you need multiple timers, keep a queue in storage and use the single alarm to drive a scheduler loop.
when is ms since epoch. Don’t pass seconds. Firing precision is about one second — don’t schedule sub-second work with it.
No recurring flag. If you want periodic work, set the next alarm at the end of your alarm handler.
The handler has a time budget. alarm() runs under its own wall-clock cap — larger than the 30-second method budget, on the order of minutes, but still bounded. A run that exceeds it counts as a failure and is redelivered.
deleteAll() does not clear the alarm. Keys and the alarm are separate; a pending alarm still fires after deleteAll(), and a handler that re-arms itself will keep running against empty state. To decommission an actor: deleteAlarm() first, then deleteAll().

Next Steps

Runtime API — ActorStorage, ActorContext, AlarmInfo
Quick Start — Scaffold, deploy, and curl an Account actor
Shared Actors — Reach one actor from many functions

Configuration

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/configuration.md

A Stateful Actor project uses the umbrella telnyx.toml manifest (the same file your [[secrets]] and [telnyx] bindings live in). The actor declaration is a [[actors]] array:

name = "account"                # function name
main = "src/index.ts"          # entry — exports the fetch handler (and the class, if this func owns the type)
compatibility_date = "2026-05-01"

[[actors]]
binding = "ACCOUNT"           # the property on env — your handle
type    = "Account"           # the class to instantiate per name

Field	Meaning
`name`	Function name (used by the platform to register the func)
`main`	Entry module — exports the `default { fetch }` handler, plus the actor class when this function owns the type (a reference binding ships no class)
`compatibility_date`	Runtime compatibility pin
`[[actors]] binding`	The name you’ll use as `env.` from your function
`[[actors]] type`	The class name to instantiate per actor name

Constraints, enforced at ship time: binding and type must be identifiers and must not contain __; type is capped at 32 characters; binding names must be unique across all bindings in the file, and SECRETS is reserved as a binding name when the file has a [[secrets]] block. Multiple [[actors]] blocks are allowed — including two bindings pointing at the same type.

Actor Namespace — the env. this declares
Project Structure — the two-export project shape

Errors

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/api-reference/errors.md

Error	Meaning
`BlockConcurrencyTimeoutError`	`ctx.blockConcurrencyWhile`’s callback exceeded the 30s budget
`ActorOutputGateError`	A storage write initiated during a method rejected after the method returned; surfaces in place of the successful return value, with the underlying failure appended to the error message. Also raised when a `transaction` callback throws
`ActorMethodTimeoutError`	An RPC method exceeded its wall-clock budget (30s by default). The invocation fails; the instance is not torn down
`ActorFetchTimeoutError`	The actor’s `fetch(req)` handler exceeded its wall-clock budget (30s)
`CodecError`	A method argument, return value, or storage value could not be serialized (e.g. a function, a circular structure)

On the caller side, a failed stub call rejects with an Error whose name identifies the cause — for example ActorMethodError (your method threw; message preserved), ActorPrivateMethodError (_-prefixed method), or ActorUnknownMethodError. Branch on err.name if you need to distinguish them.

Actor Context — blockConcurrencyWhile
Execution Model — the output-gate guarantee behind ActorOutputGateError

Project Structure

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/guides/project-structure.md

A Stateful Actor project ships from one module that exports two things, wired together by a binding declared in telnyx.toml.

Two Exports

One module exports the actor class and a fetch handler — an ordinary Edge Compute function that calls the actor through a binding on env. The deploy pipeline routes each export to the right runtime.

import { type ActorNamespace, type ActorStub } from "@telnyx/edge-runtime";
import { Account } from "./account";
export { Account };

type AccountStub = ActorStub & Pick;
interface AccountNamespace extends ActorNamespace {
  idFromName(name: string): AccountStub;
}
interface Env { ACCOUNT: AccountNamespace }

export default {
  async fetch(req: Request, env: Env): Promise {
    const acct = new URL(req.url).pathname.slice(1);      // /acct_123
    const { amount } = (await req.json()) as { amount: number };
    const result = await env.ACCOUNT.idFromName(acct).debit(amount);
    return Response.json(result);
  },
};

The Binding

env.ACCOUNT is declared in telnyx.toml as an [[actors]] entry — binding is the property on env, type is the class to instantiate per name:

name = "account-svc"
main = "src/index.ts"

[[actors]]
binding = "ACCOUNT"   # the property on env — your handle
type    = "Account"   # the class to instantiate per name

See the Runtime API for the full telnyx.toml actor block. The Quick Start builds and deploys exactly this shape — the Account actor plus its fetch handler — end to end.

Next Steps

Shared actors — reach one actor type from multiple functions
Addressing — naming and routing instances
Runtime API — the binding surface

Local Development

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/local-development.md

A plain Edge Compute function is an ordinary program you run and curl directly — the Functions local-dev guide covers that. A Stateful Actor project is different: the fetch handler reaches its actors through an env. call, and that binding resolves only against a running actor runtime. There is no in-process emulation to fall back on. telnyx-edge dev supplies the missing runtime. It generates the actor stack your project needs, boots it in Docker, serves your fetch handler on a local port, and hot-reloads on save — so env. calls hit real actors before you ship. telnyx-edge dev is a development command; it does not deploy anything. When it works locally, ship with telnyx-edge ship.

Prerequisites

Docker, running. The stack is a set of containers booted with docker compose.
A telnyx.toml umbrella project — the two-export shape from Project structure: one module that exports an actor class and a fetch handler, wired by an [[actors]] binding. Run telnyx-edge dev from the directory that holds the manifest, or point at it with -f/--from-dir. Without a telnyx.toml, the command errors:
❌ No project manifest found 💡 Run 'telnyx-edge dev' from a directory containing a telnyx.toml manifest.
The Quick Start scaffolds exactly this shape with telnyx-edge new-func --actor.

The Loop

From an umbrella project directory:

telnyx-edge dev

This bundles the project, generates the stack under .telnyx/dev, and boots it. Your fetch handler is served on http://localhost:8787 (change it with --port). Exercise it the same way the Quick Start exercises the deployed URL — but against localhost, and with actors resolving locally:

B=http://localhost:8787

curl -sS -X POST $B/accounts/alice/deposit -H 'content-type: application/json' -d '{"amount":100}'
# → {"account":"alice","balance":100}
curl -sS -X POST $B/accounts/alice/debit   -H 'content-type: application/json' -d '{"amount":30}'
# → {"account":"alice","ok":true,"balance":70}
curl -sS $B/accounts/alice/balance
# → {"account":"alice","balance":70}

Each env.ACCOUNT.idFromName(...) call routes to a real actor instance in the local stack — the same code path that runs deployed. Edit your actor class or fetch handler and save; telnyx-edge dev watches the source and hot-reloads the affected runtime. Actor state lives in the stack’s Postgres store, so it survives a reload — alice is still 70 after you edit and save. Press Ctrl-C to stop watching. The stack keeps running; the command only detaches the file watcher.

What the Stack Contains

telnyx-edge dev writes the stack under .telnyx/dev and runs it with docker compose. It is a local stand-in for the deployed platform, containing:

the function runtime — serves your fetch handler on the published port;
the actor runtime — hosts your actor instances;
a Dapr sidecar for each runtime, plus Dapr placement — the routing layer that sends each actor name to its owner;
a Postgres actor state store — where ctx.storage persists, so state survives reloads.

env. calls from the function runtime reach the actors in the actor runtime through this layer. This is what a plain func.toml function lacks: it has no local binding emulation, so binding-backed code paths only run once deployed.

Flags

Flag	Default	Purpose
`--port int`	`8787`	Host port to publish the function runtime on.
`--no-watch`	—	Boot the stack and return, without watching for changes.
`--generate-only`	—	Write the stack files under `.telnyx/dev` but do not run `docker compose`.
`-f, --from-dir string`	—	Path to the project directory (relative, absolute, or `~/path`).
`--function-image string`	`telnyx/function-runtime:dev`	Container image for the function runtime.
`--actor-image string`	`telnyx/actor-runtime:dev`	Container image for the actor runtime.
`-v, --verbose`	—	Verbose logging.

Use --generate-only to inspect or customize the generated compose stack before booting it, and --no-watch when you want the stack up for an out-of-band test run (for example, from a CI script) rather than an interactive edit loop.

Notes

Actor state survives reloads. Because ctx.storage persists to the stack’s Postgres store, a hot reload does not reset your instances — balances, counters, and any other state carry across saves. Tear the stack down with docker compose (or remove .telnyx/dev) when you want a clean slate.
Ctrl-C leaves the stack running. It stops the watcher, not the containers. Stop the stack explicitly with docker compose when you’re done.
A telnyx.toml is required. telnyx-edge dev runs umbrella projects. A single-function func.toml project has no actors to host — develop those with the Functions local-dev workflow instead.

Next Steps

Quick Start — scaffold, write, and deploy an Account actor end to end
Project structure — the two-export shape telnyx-edge dev runs
Deploy — ship, revisions, and rollback

Shared Actors

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/shared-actors.md

A shared actor is a single Stateful Actor type reachable from two or more Edge Compute functions on the same account. The function that ships the actor class owns the actor; other functions on the same account declare the same type under their own binding name and ship no class — their binding routes to the owner’s actor and its state.

Split read and write paths into separate functions with their own auth, rate limits, and deploy cadence — without duplicating state.
Let a second function call into a domain the first one owns (e.g., a reporting function reads an account actor that a payments function owns).
Keep one durable actor behind many entrypoints. Both functions talk to the same per-name state; writes through one binding are visible to reads through the other.

Both functions must be on the same account — shared actors are bounded by account.

The Pattern

The owner function is a normal Stateful Actor project — it ships the class. The reference function declares the same type under a different binding and ships no actor class — its binding routes to the owner’s actor and state; no second instance is created. There’s no new-func flag for “reference-only,” so the workflow is: scaffold with --actor (to mint a func_id and write telnyx.toml), then drop the actor class and rename the binding.

Walkthrough: a Read-Only Account Reference

Prereq: an owner function for the type already shipped on your account (the account from the Quick Start, type Account).

1. Mint a `func_id` and scaffold, then drop the class

telnyx-edge new-func --actor --name=account-readonly   # registers the func, writes func_id
cd account-readonly
rm -f src/counter.ts                                    # the ref ships no actor class

2. Point `telnyx.toml` at the owner’s type under a new binding

Edit the [[actors]] block — keep type equal to the owner’s type, change binding:

[[actors]]
binding = "READONLY"    # this func's own handle
type    = "Account"     # SAME type the owner declares → shared actor

Leave name, main, compatibility_date, and the [edge_compute] func_id as scaffolded.

3. Replace `src/index.ts` with a class-free handler that calls `env.READONLY`

import {
  type ActorNamespace,
  type ActorStub,
  type IdFromNameOptions,
} from "@telnyx/edge-runtime";

// Hand-rolled stub narrowing (mirrors the owner's read surface; no local class).
type AccountStub = ActorStub & {
  balance(): Promise<{ balance: number }>;
};
interface AccountNamespace extends ActorNamespace {
  idFromName(name: string, options?: IdFromNameOptions): AccountStub;
}
interface Env { READONLY: AccountNamespace }   // <- the binding from telnyx.toml

export default {
  async fetch(req: Request, env: Env): Promise {
    const url = new URL(req.url);
    if (url.pathname === "/health/liveness") return new Response("ok");
    if (url.pathname === "/health/readiness") return new Response("ok");

    // Read-only view: balance for an account
    const m = url.pathname.match(/^\/accounts\/([^/]+)\/balance$/);
    if (m && req.method === "GET") {
      const result = await env.READONLY.idFromName(m[1]!).balance();
      return Response.json({ account: m[1], ...result, via: "READONLY->Account(shared)" });
    }
    return new Response("not found", { status: 404 });
  },
};

Key point: no export class Account in this file. The bundler roots at main, so with nothing importing the class, the reference bundle ships class-free (a few KB) — that’s what makes it reference-only.

4. Install deps and ship (same as the owner)

npm install
telnyx-edge ship

REF=https://account-readonly-.telnyxcompute.com
OWN=https://account-.telnyxcompute.com

# Write via the owner (ACCOUNT binding) — carol is a fresh account name
curl -sS -X POST $OWN/accounts/carol/deposit \
  -H 'content-type: application/json' -d '{"amount":100}'

# Read via the reference (READONLY binding) → same balance
curl -sS $REF/accounts/carol/balance
# → {"account":"carol","balance":100,"via":"READONLY->Account(shared)"}

Write through ACCOUNT, read through READONLY, same balance → one durable actor (Account), two functions. Both must be on the same account; the reference’s type must exactly match the owner’s.

Rules of Thumb

Same account, same type. Reference bindings whose type doesn’t match an owner already on the account won’t resolve.
Only one function owns the class. The owner ships the actor class; every other function declares the same type and ships no class.
Renaming the binding is fine. Each function picks its own binding name — that’s the property on env for that function. The type is what glues them together.
Reference bundles are small. With no class import, the bundler emits a class-free bundle. Keep it that way: don’t import the actor class from your reference function.

Next Steps

Quick Start — ship the owner function this reference calls into
Runtime API — ActorNamespace, ActorStub, and the binding surface
Alarms — schedule deferred work from inside an actor method

When to Use Stateful Actors

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/guides/when-to-use.md

Use a stateful actor when an entity has state that must be mutated coherently across many requests — a cart, a chat room, a call leg’s media state, a per-user rate limiter, a job coordinator. One instance per name gives you serialized, durable, private state for that entity without locks or a shared database.

When Not to Reach for One

Stateless work (routing, transforms, independent fan-out): use a plain function. An actor only adds a routing hop and a serialization point you don’t need.
A global counter or singleton: one name is one single-threaded instance is one throughput ceiling. Route everything through idFromName("global") and you’ve rebuilt the single-lock bottleneck. Shard across many names so load spreads across instances.
Large blobs or bulk scans: the keyspace holds one entity’s working set, not a warehouse. Use object storage or a database.
Cross-entity transactions or ad-hoc queries: each instance is its own consistency domain. Within one actor, writes are serialized and transaction() gives you atomic multi-key updates — but there is no transaction across two actors, and there’s no JOIN across them. If you need a transaction spanning many entities, or to query across them, that’s what a database is for — keep it.

A single instance processes calls serially, so its ceiling is roughly 1 / (method wall-time) calls per second — the same ceiling one thread per account gives you. Sharding by a well-chosen name is how you scale.

Next Steps

How it works — the execution model and its limits
Addressing — choosing names that spread load
Shared actors — one actor, many functions

Key-Value

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/guides/storage/key-value.md

Every Stateful Actor has private, durable key/value storage at this.ctx.storage. It is the default place to keep an entity’s state: a cart’s items, a call leg’s status, a per-user counter. Reach for it first, and drop to SQL only when a lookup by key isn’t enough and you’d otherwise scan. The store is private, strongly consistent, and transactional: only this actor instance reads and writes its keys, its methods run one at a time (serialized turns), and a write that returns successfully is durable — it survives the actor being evicted, relocated, or its pod replaced. Reads always reflect your prior writes. This is a guide. For the exact method signatures, list options, and codec rules, see the Actor Storage reference.

Reading and Writing

get and put are the whole surface for simple state. Both are async — they may cross the network — so await them:

import { StatefulActor } from "@telnyx/edge-runtime";

export class Cart extends StatefulActor {
  async add(item: string) {
    const items = (await this.ctx.storage.get("items")) ?? [];
    items.push(item);
    await this.ctx.storage.put("items", items);
    return items.length;
  }

  async clear() {
    await this.ctx.storage.delete("items");   // returns true iff the key existed
  }
}

State is lazy per get — nothing is preloaded when the actor activates; you read a key when you need it. Values round-trip through a codec, so JSON natives plus Date, Map, Set, typed arrays, ArrayBuffer, BigInt, and RegExp come back as what you stored. Functions, class instances, promises, and circular structures are rejected at the write. Keys are strings. Those starting with __telnyx_ are reserved for the runtime — writes to them are rejected.

Listing Keys

list returns a Map in lexicographic key order, which makes prefixes a natural grouping:

// Every message in a room, in order:
const messages = await this.ctx.storage.list({ prefix: "msg:" });

// The 20 most recent, newest first:
const recent = await this.ctx.storage.list({
  prefix: "msg:",
  reverse: true,
  limit: 20,
});

limit defaults to 128 and maxes at 1000. Use start / startAfter / end to page through a large keyspace. See the reference for the full ListOptions.

Atomic Updates

transaction batches multiple keys into one atomic unit — all of the writes land, or none do:

await this.ctx.storage.transaction(async (txn) => {
  const balance = (await txn.get("balance")) ?? 0;
  await txn.put("balance", balance - amount);
  await txn.put("updated_at", Date.now());
});

If the callback throws, its buffered writes are discarded. Note that a thrown transaction also fails the enclosing method call — it is not a “try the write, continue on failure” tool. See the reference for the exact semantics.

Clearing an Actor

deleteAll() atomically removes every key for this actor. It does not clear a pending alarm — delete that separately if you want the actor fully reset.

Key/Value or SQL?

Both live under this.ctx.storage, are durable and strongly consistent, and can be used together in the same actor.

Key/value (this page): simple keyed state, prefix listing, atomic multi-key updates. The default.
SQL: relational shape, aggregates, GROUP BY, secondary indexes, and joins within one actor — when a keyed lookup isn’t enough.

SQL storage — the ctx.storage.sql guide
Actor Storage reference — full method signatures and codec rules
Alarms — scheduled self-wakeups

SQL

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/guides/storage/sql.md

Every Stateful Actor has a private, durable embedded SQLite database reachable at this.ctx.storage.sql. It sits beside the key/value store under the same this.ctx.storage, but it is a separate engine: one SQLite database per actor instance, queried with real SQL. Reach for it when a single entity’s state is relational or needs queries the key/value store can’t answer without a scan — aggregates, GROUP BY, secondary indexes, joins within the one actor. It is not a shared database: each instance sees only its own data, and there are no cross-actor queries or joins. The database is private, strongly consistent, and transactional: one actor instance is the only reader and writer of its database, its methods run one at a time (serialized turns), and a write that returns successfully is durable at turn granularity — it survives the actor being evicted, relocated, or its pod replaced. Reads always reflect your prior writes. Stateful Actors are in Beta. ctx.storage.sql requires @telnyx/edge-runtime 0.6.0 or later; the transactionSync() type ships in 0.8.0, so use the latest SDK.

The Surface

interface SqlStorage {
  exec>(query: string, ...bindings: SqlValue[]): SqlCursor;
}

interface SqlCursor extends Iterable {
  toArray(): T[];
}

type SqlValue = null | number | string | ArrayBuffer;

exec is synchronous — it does not return a Promise. This is deliberate and unlike every other member of ctx.storage: the database is a local file in the actor’s own process, so there is no network hop to await.

import { StatefulActor } from "@telnyx/edge-runtime";

export class Inventory extends StatefulActor {
  async record(sku: string, cents: number) {
    this.ctx.storage.sql.exec(
      `CREATE TABLE IF NOT EXISTS orders(sku TEXT, cents INTEGER, ts INTEGER)`,
    );
    this.ctx.storage.sql.exec(
      `INSERT INTO orders(sku, cents, ts) VALUES (?, ?, ?)`,
      sku,
      cents,
      Date.now(),
    );
    // An aggregate the key/value store can't answer without scanning every key:
    return this.ctx.storage.sql
      .exec(
        `SELECT sku, SUM(cents) AS total FROM orders
         GROUP BY sku ORDER BY total DESC LIMIT 5`,
      )
      .toArray();
  }
}

There is no schema step in the manifest — any actor that calls ctx.storage.sql gets a database, created on first use. Create your tables with CREATE TABLE IF NOT EXISTS (a cheap no-op once they exist) at the top of the methods that need them.

Binding Parameters

Use positional ? placeholders and pass the values as trailing arguments. Always bind user input — never build SQL by string concatenation. (Binding here is SQL’s own term for attaching values to placeholders — no relation to the telnyx.toml bindings your function receives on env.)

const rows = this.ctx.storage.sql
  .exec(`SELECT * FROM orders WHERE sku = ? AND cents > ?`, sku, 1000)
  .toArray();

A bound value must be one of four types: null, number, string, or ArrayBuffer (for binary). Result columns come back as those same four types:

SQLite type	JavaScript value you get back
`INTEGER`	`number`
`REAL`	`number`
`TEXT`	`string`
`BLOB`	`ArrayBuffer`
`NULL`	`null`

Reading Results: the Cursor

exec returns a SqlCursor — a single-pass iterator over the result rows. Drain it once, either by iterating or with toArray():

// Drain to an array (the common case):
const all = this.ctx.storage.sql.exec(`SELECT n FROM nums ORDER BY n`).toArray();

// Or stream row by row, without materializing the whole set:
for (const row of this.ctx.storage.sql.exec(`SELECT n FROM nums ORDER BY n`)) {
  handle(row.n);
}

Single-pass means the rows are consumed as you read them. After you iterate a cursor to the end, toArray() on that same cursor returns []; calling toArray() a second time also returns []. If you iterate partway and then call toArray(), you get the rest of the rows. Run exec again for a fresh pass. exec is generic in the row type — exec(...) types the returned rows — but the type is a compile-time assertion only, not validated at runtime, so make sure your query returns those columns.

Multiple Statements in One `exec`

A query string may contain several ;-separated statements — useful for pasting a schema or a small migration. Every statement executes, in order; the bound parameters apply to the last statement, and the returned cursor is over the last statement’s rows:

const rows = this.ctx.storage.sql
  .exec(
    `CREATE TABLE IF NOT EXISTS t(x INTEGER);
     INSERT INTO t VALUES (1);
     SELECT x FROM t WHERE x >= ?;`,
    1,
  )
  .toArray(); // the final SELECT's rows; the CREATE and INSERT ran too

Statements run independently — if one fails, exec throws, but the statements before it have already been applied. Wrap the batch in a transactionSync callback when it must be all-or-nothing. Multi-statement splitting is a best-effort TypeScript tokenizer, not exact SQLite parsing. It handles all realistic SQL, but unquoted keyword-identifiers (a column named end, begin, or case in a deep position) can confuse the splitter. Quote reserved-word identifiers ("end") to avoid edge cases. Exact parity is tracked in COMPUTE-470.

Transactions

Wrap related writes so they commit together — or roll back together — with transactionSync. It runs your callback synchronously, commits when it returns, and rolls back every write if it throws:

async transfer(from: string, to: string, cents: number) {
  this.ctx.storage.transactionSync(() => {
    this.ctx.storage.sql.exec(`UPDATE accounts SET cents = cents - ? WHERE id = ?`, cents, from);
    this.ctx.storage.sql.exec(`UPDATE accounts SET cents = cents + ? WHERE id = ?`, cents, to);
    // throw here — e.g. on an overdraft check — and neither UPDATE is applied
  });
}

The callback returns a value — transactionSync passes it through, so you can read back a result computed inside the transaction. Two rules, both enforced by the runtime:

transactionSync is the only transaction API. Raw transaction-control statements — BEGIN, COMMIT, ROLLBACK, SAVEPOINT — are rejected by exec() with SqlTransactionControlError, anywhere in a statement batch. (An open transaction left dangling across method calls would have no owner; the callback shape makes that impossible.)
The callback must be synchronous. Passing an async function throws SqlAsyncTransactionError and commits nothing — the transaction commits when the callback returns, so statements after an await would run outside it. Do async work before or after, not inside.

Because a single actor instance processes one method at a time, you never contend with another writer inside your own database — the actor is the lock.

Bulk Writes

Each standalone exec write commits and flushes to disk on its own, which is slow in a loop. Wrap a batch in one transactionSync and it commits (and flushes) once:

this.ctx.storage.transactionSync(() => {
  for (const row of rows) this.ctx.storage.sql.exec(`INSERT INTO t(v) VALUES (?)`, row);
});

The difference is large: thousands of individual auto-commit inserts take seconds; the same inserts inside one transaction take tens of milliseconds. Batch anything hot.

Indexes

The database holds one entity’s working set, but scans still cost time and — as it grows — memory. Add an index on any column you filter or order by frequently:

this.ctx.storage.sql.exec(`CREATE INDEX IF NOT EXISTS orders_by_sku ON orders(sku)`);

Limits

1 GB per actor database. Enforced by the engine — writes past it fail.
2 MiB per bound value. A bind larger than 2 MiB (2,097,152 bytes) is rejected with SqlParameterTooLargeError before the statement runs. There is no cap on output row size.
Up to 32,766 bound parameters in a single statement (SQLite’s variable limit).
Integers come back as JavaScript number. SQLite stores 64-bit integers, but exec returns integer columns as JS numbers — the same design as Cloudflare’s SQLite storage and D1, neither of which returns BigInt from the query API. A value beyond Number.MAX_SAFE_INTEGER (2^53 − 1, i.e. 9007199254740991) can be written and compared in SQL, but reading that column throws RangeError: Value is too large to be represented as a JavaScript number — a loud failure rather than a silently less-precise number. Store large ids, bitmasks, or nanosecond timestamps as TEXT (or BLOB), or keep integers within the safe range.
Foreign keys are ON — a REFERENCES violation raises FOREIGN KEY constraint failed.
Failed statements (syntax errors, constraint violations) throw from exec; the actor keeps running, so catch and handle them like any other error.

SQL or Key/Value?

Both live under this.ctx.storage, are durable and strongly consistent, and can be used together in the same actor.

Key/value (get/put/list): simple keyed state, prefix listing, atomic multi-key updates — reach for it by default when a lookup by key is all you need.
SQL (ctx.storage.sql): relational shape, aggregates, GROUP BY, secondary indexes, and joins within one actor. Reach for it when a keyed lookup isn’t enough and you’d otherwise scan.

Key-Value storage — the get/put/list surface
Actor Storage reference — the full ctx.storage contract
Execution model — why exec needs no lock

WebSockets

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/websockets.md

WebSocket support for Stateful Actors is in beta. APIs and limits may change before general availability. A client opens one WebSocket. Your function runs once, at the handshake — check the upgrade, authenticate, decide which actor owns this connection — and hands off. From then on the actor owns the live socket: each inbound frame is dispatched like a method call — one at a time per instance, serialized with RPCs and alarms — durable state is ordinary ctx.storage, and replies stream straight back with ws.send(). That shape removes the plumbing a chat, agent, or live-session backend usually accretes. When the connection tier and the state tier are separate fleets, every message crosses a pub/sub bridge on the way in and needs a reverse channel to find whichever host holds the socket on the way out. Here the socket and the state live in the same single-threaded instance — a message handler is a plain method body that reads storage, writes storage, and sends. Any actor class can terminate WebSockets — declaring the webSocket() method is the whole opt-in; there is no flag to enable, in telnyx.toml or anywhere else. Actor names used with sockets must be printable ASCII with no leading or trailing whitespace, and any header values your function forwards must be printable ASCII today.

The Two Halves

	Runs	Responsible for
Function	once per connection, at the handshake	reject non-upgrades (`426`), authenticate, rate-limit, resolve `idFromName`, stamp what it learned as headers
Actor	once per frame, and per close/error event	per-message logic, durable state, replies

The boundary is strict: per-message logic never lives in the function. After the handshake the function is done — frames are delivered only to the actor. Everything the function learned rides the forwarded request as headers, so the socket reaches the actor already authenticated. The req the actor sees carries only those application headers; transport and handshake headers (Upgrade, Sec-WebSocket-*) are stripped. The smallest complete pairing:

// The function half — runs once, at the handshake.
export default {
  async fetch(req: Request, env: Env): Promise {
    if (req.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
      return new Response("expected websocket", { status: 426 });
    }
    const user = await authenticate(req);      // per-connection work — done once, here
    if (!user) return new Response(null, { status: 401 });

    const headers = new Headers(req.headers);
    headers.set("x-user", user.id);            // what you learned rides as headers
    return env.ROOM.idFromName(roomFor(req)).fetch(new Request(req, { headers }));
  },
};

// The actor half — owns the live socket from here on.
export class Room extends StatefulActor {
  async webSocket(ws: WebSocket, req: Request): Promise {
    const user = req.headers.get("x-user");    // already authenticated
    ws.on("message", async (data) => {         // messages dispatch one at a time
      const n = ((await this.ctx.storage.get("n")) ?? 0) + 1;
      await this.ctx.storage.put("n", n);
      ws.send(`${user} #${n}: ${data}`);       // streams straight back
    });
  }
}

(authenticate and roomFor stand in for your auth and routing; a complete, runnable version is below.) The actor opts in by defining one optional method:

async webSocket(ws: WebSocket, req: Request): Promise

ws has Node ws socket semantics — ws.on("message", (data, isBinary) => ...), ws.send(data), ws.close(code, reason) — not a browser socket and not Cloudflare’s WebSocketPair/accept(). Text and binary frames both work. An actor with no webSocket() method closes incoming sockets with code 1011.

A Chat Room, End to End

One module exports both halves. The ChatRoom actor holds the room’s messages and its live sockets; the default export is the front door.

# telnyx.toml
name = "chat"
main = "src/index.ts"
compatibility_date = "2026-05-01"

[[actors]]
binding = "ROOM"
type    = "ChatRoom"

// src/index.ts
import { StatefulActor, type ActorNamespace } from "@telnyx/edge-runtime";
import type { WebSocket } from "ws";
// `ws` is a transitive dependency of @telnyx/edge-runtime. With npm it resolves
// automatically; with pnpm or other strict layouts, install @types/ws yourself.

export class ChatRoom extends StatefulActor {
  async webSocket(ws: WebSocket, req: Request): Promise {
    // The front door authenticated this connection and stamped x-user; by the
    // time the socket reaches the actor, it is already authenticated.
    const user = req.headers.get("x-user") ?? "anonymous";

    ws.send(JSON.stringify({ type: "welcome", user, present: this.ctx.count() }));

    ws.on("message", async (data, isBinary) => {
      if (isBinary) return; // this room speaks text JSON

      // Parse defensively: an uncaught throw in a handler closes the
      // socket with code 1011.
      let text: string;
      try {
        ({ text } = JSON.parse(String(data)) as { text: string });
      } catch {
        ws.send(JSON.stringify({ type: "error", error: "frames must be JSON" }));
        return;
      }

      // Durable read-modify-write. Messages dispatch one at a time per
      // instance, so this never races another socket's frame — no lock, no
      // transaction.
      const seq = ((await this.ctx.storage.get("seq")) ?? 0) + 1;
      await this.ctx.storage.put("seq", seq);
      await this.ctx.storage.put(`msg:${seq}`, { user, text, at: Date.now() });

      // Fan out to every live socket on THIS room, then ack the sender.
      const delivered = this.ctx.broadcast(
        JSON.stringify({ type: "message", seq, user, text }),
      );
      ws.send(JSON.stringify({ type: "sent", seq, delivered }));
    });

    // Close and error events go through the same single-threaded dispatch;
    // a storage write in a close handler still commits. The runtime removes the socket from
    // count()/broadcast() on its own — register these only for your own
    // bookkeeping.
    ws.on("close", async (code) => {
      await this.ctx.storage.put("lastLeave", { user, code, at: Date.now() });
    });
    // Keep an error listener so transport errors land in your logs instead of
    // vanishing; the runtime already tears the socket down on error.
    ws.on("error", (err) => console.error("ws error", err));
  }

  // Plain RPC on the same actor — same instance, same one-at-a-time dispatch.
  async messageCount(): Promise {
    return (await this.ctx.storage.get("seq")) ?? 0;
  }
}

interface Env {
  ROOM: ActorNamespace;
}

export default {
  async fetch(req: Request, env: Env): Promise {
    const url = new URL(req.url);
    const match = url.pathname.match(/^\/rooms\/([^/]+)$/);
    if (!match) return new Response("not found", { status: 404 });

    if (req.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
      return new Response("expected websocket", { status: 426 });
    }

    // Browser WebSocket clients cannot set request headers, so credentials
    // ride the URL. This code runs once per connection — the right place to
    // verify a signed token. The example only checks shape: forwarded header
    // values must be printable ASCII, and should be bounded.
    const user = url.searchParams.get("user");
    if (!user || !/^[\x20-\x7e]{1,128}$/.test(user)) {
      return new Response("missing or malformed ?user=", { status: 401 });
    }

    // Attach what the front door learned; overwrite anything client-supplied.
    const headers = new Headers(req.headers);
    headers.set("x-user", user);

    // Hand off: the actor named by the room owns the socket from here on.
    return env.ROOM.idFromName(match[1]!).fetch(new Request(req, { headers }));
  },
};

Connect with any WebSocket client:

websocat "wss:///rooms/lobby?user=alice"
{"type":"welcome","user":"alice","present":1}
{"text":"hello"}
{"type":"message","seq":1,"user":"alice","text":"hello"}
{"type":"sent","seq":1,"delivered":1}

Every socket opened on /rooms/lobby lands on the same ChatRoom instance; /rooms/standup is a different instance with its own seq, its own messages, and its own sockets. ctx.count() and ctx.broadcast() see only this instance’s sockets — a broadcast never crosses actor ids, and a socket never moves between them.

Sending to Some Sockets, Not All

ctx.broadcast() is all-or-nothing: one frame to every socket on the instance. There is no built-in way to address a subset — no socket list to filter, no per-socket tags. “Everyone except the sender” and “just this user” are yours to build, and on a single-threaded instance the whole mechanism is one Map: filled in webSocket(), pruned in the close listener.

export class Room extends StatefulActor {
  // Keyed by socket, not by user: one user may hold several sockets (two tabs).
  private peers = new Map();

  async webSocket(ws: WebSocket, req: Request): Promise {
    const user = req.headers.get("x-user") ?? "anonymous";
    this.peers.set(ws, { user });
    // Close events dispatch one at a time like everything else, so this
    // delete never races a message handler mid-iteration.
    ws.on("close", () => this.peers.delete(ws));

    ws.on("message", (data) => {
      // Everyone except the sender:
      for (const peer of this.peers.keys()) {
        if (peer !== ws) peer.send(`${user}: ${data}`);
      }
    });
  }

  // One named user — every socket they have open. Call it from a message
  // handler that routes a direct-message frame, or expose it as an RPC.
  sendTo(user: string, data: string): number {
    let sent = 0;
    for (const [peer, meta] of this.peers) {
      if (meta.user === user) {
        peer.send(data);
        sent++;
      }
    }
    return sent;
  }
}

The map is a plain instance field, and here — unlike almost everywhere else on the platform — that is correct, with nothing written to ctx.storage. Sockets and instance memory share a lifetime: an open socket keeps the instance resident, and the events that replace an instance — a redeploy, an infrastructure restart — sever its sockets too. A fresh instance therefore starts with no sockets and an empty map, never one without the other; there is nothing to persist and nothing to rebuild. What should outlive the connection — who was here, what they said — goes in ctx.storage as usual.

Messages Are Single-Threaded, Like Everything Else

An inbound frame is dispatched like a method call, under the execution model’s “one call at a time” guarantee: while a message handler runs, frames from other sockets on the same instance, RPC calls, and the alarm all wait. That is exactly what makes the chat room’s read-modify-write on seq safe with any number of concurrent senders. The consequences:

The 30-second method budget applies to each message handler. A handler that throws or exceeds it closes the socket with code 1011.
ws.send() is immediate — and not held for durability. A method’s return value is held until your storage writes are durable; a sent frame is not. If a handler sends and then fails, the client keeps a frame describing state that never committed. If clients must act only on committed state, make frames re-derivable from storage on reconnect — the chat room’s durable seq makes gaps and replays detectable.
Keep per-message work bounded. Frames that arrive while a handler runs queue, up to 256 events or 1 MiB; overflow closes the socket with 1013 (back off before reconnecting), and a single inbound frame over 1 MiB closes it with 1009. Don’t stream minutes of work from one handler — chunk it across messages, or drive it from an alarm. ws.send() itself never blocks the handler.
High-frequency senders should coalesce. Every frame costs a full dispatch — one turn of the instance’s single thread, one queue slot — so a client emitting a stream of tiny messages (sensor readings, cursor positions, game state) spends the queue on frame count, not bytes: at 100 messages a second, a single handler that stalls for three seconds is enough to overflow the 256-event queue and close the socket with 1013. Batch logical messages into one frame — an array, flushed on a short timer or a count threshold — and loop over the batch in the handler. Fifty readings in one frame cost one dispatch and one queue slot instead of fifty; just keep the batch under the 1 MiB frame cap.

An open socket also keeps the actor in memory for the duration of the connection.

Connections End; State Doesn’t

Every connection ends. Today a connection lives at most about five minutes from the handshake — even on a socket actively exchanging frames — and the cutoff surfaces as an abnormal close (code 1006, no close frame). This cap will be raised in a future update. Function redeploys and infrastructure restarts sever sockets the same way; a deliberate close from either side is code 1000. Reconnecting is the client’s job: back off, reopen, rejoin the same name. idFromName routes the new socket back to the same actor, and everything in ctx.storage survived — the room’s messages and seq are intact; only the socket is new. A reconnect is a new socket on the actor, never a resumption of the old one. The full close-code table and reconnect guidance are on Connection Lifecycle.

Push Without an Inbound Frame

An actor runs only when something calls it — a frame, an RPC, or an alarm; time passing alone runs nothing. To push to connected clients without waiting for them to send anything, let the alarm make the call and fan out with ctx.broadcast():

export class Ticker extends StatefulActor {
  async webSocket(ws: WebSocket, req: Request): Promise {
    // First socket arms the loop; later sockets just join the fan-out.
    if ((await this.ctx.storage.getAlarm()) === null) {
      await this.ctx.storage.setAlarm(Date.now() + 3_000);
    }
  }

  async alarm(): Promise {
    this.ctx.broadcast(JSON.stringify({ type: "tick", at: Date.now() }));
    if (this.ctx.count() > 0) {
      await this.ctx.storage.setAlarm(Date.now() + 3_000); // re-arm while anyone listens
    }
  }
}

The alarm handler is an ordinary method call, so it can read storage, write storage, and send — a message handler on one socket can likewise broadcast to all of them, as the chat room does.

Outbound Requests

Egress from an actor is ordinary Node: the global fetch and the global WebSocket client both work from inside any handler — call a model API and stream its output back over the socket, or dial an upstream WebSocket, exchange frames, and close it. The dispatch rules apply unchanged: outbound work inside a message handler holds the instance’s only thread and runs under the 30-second budget, so ship interim results with ws.send() as they arrive, and chunk anything long across messages or drive it from an alarm.

Next Steps

Runtime API — webSocket(), ctx.count(), ctx.broadcast()
Connection Lifecycle — duration budget, close codes, reconnect strategy
Execution Model — the four guarantees behind single-threaded dispatch
Alarms — the delivery contract behind the push pattern
Quick Start — scaffold and deploy your first actor

Connection Lifecycle & Limits

Source: https://developers.telnyx.com/docs/edge-compute/stateful-actors/websockets/lifecycle.md

WebSocket support for Stateful Actors is in beta. APIs and limits may change before general availability. One contract underlies everything on this page: every connection ends. A redeploy severs it, the duration budget expires it, a failing handler closes it. Build for that from the start — treat the socket as disposable transport and the actor as the durable thing. Reconnecting is the client’s job; idFromName with the same name routes the new socket back to the same actor, and everything in ctx.storage is exactly where the last connection left it. A client that reconnects with backoff and re-syncs on open loses nothing but the socket.

How a Connection Is Established

Your function’s fetch runs once, at the handshake — check the Upgrade header, authenticate, pick the actor, forward. It never sees another byte of the connection; per-message logic lives in the actor’s webSocket() handler. The full front-door pattern is on the WebSockets page. What a client can rely on at and after the handshake:

The upgrade must be a GET. A non-GET request with an Upgrade header is refused with HTTP 400 — no handshake starts.
The first client-offered subprotocol is echoed. Offer ["chat.v2", "chat.v1"] and the connection is accepted with chat.v2. The actor cannot select among the offers today; it observes the echoed value as ws.protocol. Put your preferred protocol first.
Compression is never negotiated. A permessage-deflate offer is accepted without the extension; frames flow uncompressed.
Text and binary frames both work. The handler’s message listener receives (data, isBinary); binary frames round-trip byte-identically.
Protocol-level pings are answered by the platform, payload echoed. You don’t write keepalive code on the actor side.

How Connections End

Code	Meaning	What the client should do
`1000`	Normal close — either side asked for it (`ws.close(1000, ...)` on the actor, or the client).	Nothing. Don’t reconnect.
`1005`	No close code received — a bare `ws.close()` or browser close with no code argument surfaces as `1005` at the peer. Treat as deliberate if you control both sides; otherwise indistinguishable from an abnormal drop.	Reconnect if the close was not expected; otherwise no action.
`1001`	Actor going away — graceful drain before a restart or move. Graceful drain is still rolling out; today an actor-side restart can surface as `1006` instead.	Reconnect promptly; the actor comes back under the same name.
`1006`	Abnormal — the connection was severed with no close frame: the duration budget expired, a function was redeployed, or infrastructure restarted.	Reconnect with backoff.
`1009`	An inbound frame exceeded the 1 MiB cap.	Fix the client — chunk large payloads. Reconnecting without fixing it hits the same wall.
`1011`	A message handler threw or exceeded the 30-second method budget. Also sent when the actor class has no `webSocket()` handler at all (reason: `actor has no webSocket handler`).	Reconnect, but treat repeats as a server-side bug to fix, not a transient.
`1013`	Event queue overflow — frames arrived faster than handlers drained them (256 events / 1 MiB queued). The actor is overloaded.	Back off longer than for `1006` before reconnecting, and slow your send rate. High-frequency clients should batch messages into fewer frames — the queue counts events, not bytes.
`4000`–`4999`	Application-defined — the RFC 6455 private-use range. The platform doesn’t use these codes; one of them means your own actor called `ws.close()`, and the code and reason arrive exactly as the actor sent them.	Whatever your protocol assigned it — kicked, room closed, session expired. It’s a deliberate close: act on it, don’t blind-retry it.

Today, a connection lives at most about five minutes. The total-duration budget applies even to a socket actively exchanging frames; the cutoff surfaces as close code 1006 with no close frame. This is a current limit, not the contract — it will be raised in a later release. Until then, design clients to ride through a reconnect every few minutes as a matter of course. There is no separate idle kill below that budget — a socket that goes quiet for 90 seconds and then sends a frame still gets that frame delivered and handled. The duration budget is what ends it. That guarantee covers the platform’s half of the path only. NATs, corporate proxies, and load balancers between your client and Telnyx run their own idle timers, and any of them can drop a quiet connection long before the duration budget would — often silently, leaving the client holding a socket that looks open but delivers nothing. No close event fires for a drop like that, so reconnect logic alone never notices it; only traffic does. If your clients sit quiet for long stretches, send a periodic heartbeat: non-browser clients can use a protocol-level ping, which the platform answers, and browser WebSocket clients — which cannot send pings — should use a small application-level frame the webSocket() handler replies to. A heartbeat frame is one more frame through the same single-threaded dispatch, so keep it small and infrequent, and give your client library’s own idle or read timeouts the same review. Deploys sever live sockets. Shipping a new version of your function drops every connection it carries as 1006. This is another reason reconnect logic is not optional: your own deploys exercise it.

Reconnecting

A complete client. It reconnects on every close except the deliberate ones — 1000, or an application-defined 4xxx — backs off exponentially, backs off harder on 1013, and re-syncs on open — the socket is new even though the actor and its storage are not.

function connect(room: string, attempt = 0): void {
  const ws = new WebSocket(
    `wss:///rooms/${room}?user=me`,
  );
  let openedAt = 0;

  ws.onopen = () => {
    openedAt = Date.now();
    // Re-request whatever context this client needs. Durable state picked
    // up where it left off — a counter in ctx.storage that read 2 before
    // the drop reads 3 after the next message, not 1.
    ws.send(JSON.stringify({ op: "sync" }));
  };

  ws.onmessage = (ev) => {
    // ... application protocol ...
  };

  ws.onclose = (ev) => {
    if (ev.code === 1000) return; // done on purpose
    if (ev.code >= 4000) return; // app-defined — deliberate; act on it, don't retry it
    // Reset the backoff only after a connection proved stable — an actor
    // that accepts the handshake and then dies must still back off.
    if (openedAt > 0 && Date.now() - openedAt > 30_000) attempt = 0;
    const base = ev.code === 1013 ? 2_000 : 250; // overloaded → back off harder
    const delay = Math.min(base * 2 ** attempt, 30_000) + Math.random() * 250;
    setTimeout(() => connect(room, attempt + 1), delay);
  };
}

connect("standup");

Reconnect to the same name. idFromName("standup") routes to the same actor every time, so the durable sequence counters, history, and alarms of the conversation are all still there. What does not survive is anything held only in the actor’s instance fields or in the old socket itself — the same rule as the rest of the platform: only ctx.storage is real. See Lifecycle & placement.

Limits

Limit	Value	On violation
Inbound frame size	1 MiB	Close `1009`
Event queue while a handler runs	256 events / 1 MiB	Close `1013`
Per-message method budget	30 seconds	Close `1011`
Connection duration	~5 minutes today (expected to increase)	Close `1006`, no close frame
Socket scope	One actor id — `ctx.count()` and `ctx.broadcast()` reach only this id’s sockets; sockets never carry over between ids	—
Actor names used with sockets	Printable ASCII, no leading/trailing whitespace, today	Connection fails to establish
Header values your function forwards	Printable ASCII today	Connection fails to establish
Outbound frame size	No platform cap — unsent bytes wait in the actor’s memory until the client’s connection drains them	—

The queue limit is a consequence of single-threaded dispatch: an inbound frame is handled like a method call — one at a time per instance, serialized with RPCs and alarms. While one handler runs, further frames queue; a slow handler with fast senders overflows the queue and the socket closes 1013. Keep per-message work well under the 30-second budget — the queue bound is sized for handlers that finish in milliseconds, not tens of seconds. The same serialization sets the practical ceiling on how many sockets one instance should carry. The table has no socket-count row because the working bound is not a count — it is aggregate frame rate. An instance handles one frame at a time from all of its sockets combined: at one millisecond of handler work per frame, the whole instance drains at most on the order of a thousand inbound frames per second, and a ctx.broadcast() inside a handler writes one frame to every connected socket, so fan-out work grows with the audience. The 256-event queue absorbs a burst of at most a couple hundred frames, not thousands of senders talking at once. When one name’s combined rate approaches what its handlers can drain, partition the workload across names — a room per idFromName, a shard per topic or region — so each instance coordinates only the sockets whose combined traffic it can serialize. An actor is a unit of coordination, not a unit of capacity. The outbound direction is the mirror image, and it is not policed. ws.send() never blocks the handler, and the platform never drops or coalesces frames on a live connection — anything the client hasn’t drained yet waits in the actor’s memory, and ws.bufferedAmount (standard Node ws) reports how much is queued on a socket. Against a responsive client that number stays near zero; against a stalled one — a backgrounded tab, a dead radio link — every ctx.broadcast() tick adds another payload to the stalled socket’s queue. Bound what one slow consumer can cost: keep broadcast payloads small, and when updates outpace a client, send the latest state rather than queueing every delta — durable state in ctx.storage means a client that fell behind can re-sync from a snapshot instead of replaying a backlog. A socket whose bufferedAmount only grows is gone in every way that matters; close it, and the reconnect-and-re-sync logic every client here needs anyway will pick it back up.

What Holds the Actor in Memory

While a connection is open its actor stays resident — the actor is not deactivated between frames — and under today’s duration budget a connection never lives long enough for the idle eviction described in Lifecycle & placement to be a factor. The cost model follows: a million idle actors are cheap; a million actors each holding an open socket are a million resident activations. Teardown is orderly on the actor side. close and error listeners run under the same single-threaded dispatch as any other event, and a ctx.storage write inside a close handler commits — the instance stays resident until those final handlers finish, not merely until the raw socket drops. Recording “last seen” in a close handler is safe. After the last socket’s close handler finishes, the actor is an ordinary idle actor again: evictable, and revivable by the next idFromName call — or by an alarm it set while the connection was up.

Next Steps

WebSockets — the front-door pattern, the webSocket() handler, and how messages dispatch
Lifecycle & placement — eviction and restart for actors generally
Alarms — deferred work that outlives any connection

Network

Network Overview

Source: https://developers.telnyx.com/docs/network/overview.md

Introduction

Telnyx programmable networking allows users and their application to access Telnyx SIP and API endpoints without traversing the public internet, therefore offering a path with better latency and throughput. The SIP and API endpoints are:

api.telnyx.com
sip.telnyx.com and their regional counterparts
*.telnyxcloudstorage.com where * is all available storage regions, e.g. us-central-1

The users’ applications can reside in any one of the major hyperscalers, i.e. AWS, GCP, and Azure, or the users’ own data centers (as long as the user has a presence in Equinix.) This model is analogous to certain AWS concepts — From the “outside” world, a user can use a Direct Connect to connect to private resources (e.g. your EC2 instances) or public resources (e.g. S3). Though to AWS, the “outside” world is largely limited to their users’ on premise data centers.

API Concepts

Coverage

Coverage API enumerates all the supported products at each of Telnyx’s PoP. Before creating any resources, please ensure that

There is a PoP in the vicinity from where you want to connect, and
The desired resources are available at that PoP.

Equally important, depending on the resource, there are product specific coverage endpoints you must consult. Refer to the coverage guide for more detail.

Networks

It is a logically isolated virtual network. It is a pre-requisite for the creation of other elements. Refer to the network guide for more detail.

Gateways

It is a virtual node that facilitates traffic routing between your Telnyx network and an outside network. There are three types of gateways.

WireGuard Gateways (WGW); in the API, it’s named interface
Internet Gateways (IGW)
Private Wireless Gateways (PWG)

WireGuard Gateways

It is a virtual VPN concentrator implemented with the open source WireGuard protocol. It is similar to

Virtual Private Gateway in AWS
VPN Gateway in GCP
Virtual Network Gateway in Azure

Refer to the WireGuard Gateway guide for more detail.

Internet Gateways

It is an element that routes traffic to and from the internet, similar to Internet Gateway or NAT Gateway in AWS Refer to the Internet Gateways Guide

Private Wireless Gateways

It is a private packet gateway that concentrates, routes, and segments traffic for a group of SIMs. Refer to private wireless gateway guide for more detail.

Virtual Cross Connects

It is a virtual direct connection between a supported cloud provider and Telnyx. Refer to VXC guide for more detail.

Coverage

Source: https://developers.telnyx.com/docs/network/coverage.md

Generic Coverage

Individual networking resource availability is not universal across all Telnyx regions. Hence the user must ensure the desired resource is offered at the desired region. To this end, we offer a coverage API (GET /v2/network_coverage). The location parameter is hierarchical:

Parameter	Value
`region`	`EMEA`, `AMER`, `APAC`
`site`	a broad geographical area within the region, e.g. `ORD` in `AMER`
`pop`	a specific data center within the site, e.g. `CH1` in `ORD`
`name`	a human readable name, e.g. `Chicago IL, US`
`code`	the unique ID for the site, e.g. `chicago-il`

The available_services parameter is an array of all available resources that can be created at this specific location. Possible values are:

virtual_cross_connect
cloud_vpn aka wireguard interface aka wireguard gateway
private_wireless_gateway
public_internet_gateway

Here are some common usage patterns of this API.

Querying by the desired product

GET /v2/network_coverage?filter[available_services][contains]=cloud_vpn

Querying by the desired product with a location constraint

GET /v2/network_coverage?filter[available_services][contains]=cloud_vpn&filter[location.region]=AMER

Querying by the desired location

GET /v2/network_coverage?filter[location.region]=EMEA

Here is a sample response:

{
    "data": [
        {
            "available_services": [
                "virtual_cross_connect"
            ],
            "location": {
                "region": "EMEA",
                "site": "FRA",
                "pop": "FR5",
                "name": "Frankfurt, DE",
                "code": "frankfurt-de"
            },
            "record_type": "network_coverage"
        }
    ],
    "meta": {
        "total_pages": 1,
        "total_results": 1,
        "page_number": 1,
        "page_size": 25
    }
}

Virtual Cross Connects (VXC) Coverage

In the case of virtual cross connect (VXC) there are two terminating endpoints to every single connection: a cloud provider endpoint and a Telnyx endpoint. As a result, it’s insufficient to simply perform the coverage check. For example, the above API response only indicates that one end of the VXC can be terminated at the Telnyx’s FR5 PoP. It provides no information about the other terminating endpoint. To that end, we offer a VXC coverage API (GET /v2/virtual_cross_connects_coverage) to augment the generic coverage API. Here are some common usage patterns of this API. Querying by fixing Telnyx endpoint

GET /v2/virtual_cross_connects_coverage?filter[location.pop]=CH1

The response to the above query shows all the possible cloud provider endpoints at which a VXC, whose one end is terminated at Telnyx CH1 PoP, can be terminated. Querying by fixing cloud provider endpoint

GET /v2/virtual_cross_connects_coverage?filter[cloud_provider]=aws&filter[cloud_provider_region]=us-east-1

The response to the above query shows all the possible Telnyx endpoints at which a VXC, whose one end is terminated at us-east-1 of AWS, can be terminated. Here is a sample response:

{
    "data": [
        {
            "cloud_provider": "aws",
            "cloud_provider_region": "us-east-2",
            "location": {
                "region": "AMER",
                "site": "ORD",
                "pop": "CH1",
                "name": "Chicago IL, US",
                "code": "chicago-il"
            },
            "available_bandwidth": [
                50
            ],
            "record_type": "virtual_cross_connects_coverage"
        }
    ],
    "meta": {
        "total_pages": 1,
        "total_results": 1,
        "page_number": 1,
        "page_size": 25
    }
}

The available_bandwidth is in Mbps.

Networks Configuration

Source: https://developers.telnyx.com/docs/network/networks.md

A network instance is a prerequisite for the creation of all other elements. Here is a sample request:

Request sample

Don’t forget to update YOUR_API_KEY here.

POST /v2/networks HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Content-Length: 40

{
  "name": "my_first_virtual_network"
}

Here is a sample response:

{
    "data": {
        "created_at": "2024-07-17T15:19:10.640289Z",
        "id": "58b42010-de88-4d9b-a164-d0b8170100bc",
        "updated_at": "2024-07-17T15:19:10.640289Z",
        "name": "my_first_virtual_network",
        "record_type": "network"
    }
}

API reference is available here.

WireGuard Gateway Setup

Source: https://developers.telnyx.com/docs/network/gateways/wireguard-gateway.md

On naming convention: in the API Reference, certain legacy documentations, and the Mission Control Portal, WireGuard Gateways are referred to as “Wireguard Interfaces”. In this guide and all guides under the “Networking” collection, the term WireGuard Gateway is used consistently. The devices that connect to it are referred to as WireGuard Peers or simply Peers

Introduction

WireGuard Gateway (WGW) is an element to which peers can connect and form a VPN over the public internet. It’s built on top of the WireGuard implementation.

Creating a WGW

Step 1: Create a Network

Follow this guide.

Step 2: Check for Coverage

Follow this guide. Use filter[available_services][contains]=cloud_vpn to look for a desired site at which to deploy the WGW. ashburn-va is chosen for the subsequent steps.

Step 3: Create a WGW

Using the network created from Step 1 and the chosen region from Step 2, create the WGW. Once a WGW is created on a specific network, it cannot be “migrated” to another one; it needs to be recreated on the other network. Double check the correct network_id is used in the following API request.

POST /v2/wireguard_interfaces HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 115

{
  "network_id": "91446ee3-9f6a-49ed-8d9b-1bd3e1529324",
  "name": "wgw-08071029",
  "region_code": "ashburn-va"
}

It’s not yet ready to be used immediately after the creation since its status is provisioning.

{
    "data": {
        "name": "wgw-08071029",
        "status": "provisioning",
        "public_key": "XXX",
        "created_at": "2024-08-07T15:29:52.068774Z",
        "network_id": "91446ee3-9f6a-49ed-8d9b-1bd3e1529324",
        "enable_sip_trunking": false,
        "id": "b6a10cb9-6c1a-40bd-96e3-d4f8eb2bd6c5",
        "region_code": "ashburn-va",
        "updated_at": "2024-08-07T15:29:53.493104Z",
        "region": {
            "code": "ashburn-va",
            "name": "Ashburn VA, US",
            "record_type": "region"
        },
        "record_type": "cloud_vpn",
        "endpoint": "64.16.243.3:5107",
        "server_ip_address": "172.27.0.1/24"
    }
}

endpoint denotes the publicly routable IP to which peers will connect over the public internet.
server_ip_address is the private subnet range the WGW and peers will use with WGW occupying the first usable IP.

Step 4: Wait for Status Transition

The expected time for status to transition to provisioned is approximately 5 minutes. You can poll the WGW to check for status.

GET /v2/wireguard_interfaces/b6a10cb9-6c1a-40bd-96e3-d4f8eb2bd6c5 HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

Creating Peers

In the following example, a peer is created for the WGW from the previous section.

POST /v2/wireguard_peers HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 102

{
    "name": "mbp-local-peer",
    "wireguard_interface_id": "b6a10cb9-6c1a-40bd-96e3-d4f8eb2bd6c5"
}

In the response, you are given the key pair with which to configure your peer. private_key is only given to you ONCE in the creation API response. It must be stored by you.

{
    "data": {
        "name": "mbp-local-peer",
        "public_key": "ZZZ",
        "last_seen": null,
        "created_at": "2024-08-07T15:45:13.569576Z",
        "id": "7fc4c14e-ff94-4a97-b156-35f1feeb29b8",
        "wireguard_interface_id": "b6a10cb9-6c1a-40bd-96e3-d4f8eb2bd6c5",
        "updated_at": "2024-08-07T15:45:13.922425Z",
        "record_type": "wireguard_peer",
        "private_key": "YYY"
    }
}

Simpler still, you may use the following API to obtain the conf file template.

GET /v2/wireguard_peers/7fc4c14e-ff94-4a97-b156-35f1feeb29b8/config HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

After inserting the private_key, you can import the conf file on the peer.

# Telnyx CloudVPN config. Target OS: Linux

[Interface]
PrivateKey = YYY
Address = 172.27.0.2/32

[Peer]
PublicKey = XXX
AllowedIPs = 172.27.0.0/24
Endpoint = 64.16.243.3:5107
PersistentKeepalive = 1

[Interface] refers to the local peer.

PrivateKey should have the value returned in the private_key parameter.
Address is the next available IP in the subnet range. In this case, since this is the first peer, it gets the next IP after the WGW.

[Peer] refers to the WGW created previously.

PublicKey is that of the WGW
AllowedIPs is the network this peer has access to. See this excellent explanation.
Endpoint is the publicly exposed IP to which peers can connect
PersistentKeepalive is a default parameter that can be ignored.

Configuring Peers

With the conf file, you can import that onto the host. Here are the environment specific guides:

Use Cases

In this section, we introduce 3 use cases that WGW can accommodate by itself.

Use Case 1: Multi-Cloud Network

WGW can be used as a VPN concentrator server to facilitate traffic between peers. In the following example, we will construct this architecture.

Peer in Cloud A is an EC2 instance in AWS.
Peer in Cloud B is a Droplet in DigitalOcean.

It will be demonstrated that it’s extremely trivial to set up a “multicloud” network.

Peer in Cloud A

This EC2 instance runs an apache server but only allows inbound SSH traffic.

As a result, it’s unreachable from the public internet.

user@localhost ~ % ping 34.201.0.189
PING 34.201.0.189 (34.201.0.189): 56 data bytes
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
^C
--- 34.201.0.189 ping statistics ---
3 packets transmitted, 0 packets received, 100.0% packet loss
user@localhost ~ % curl 34.201.0.189
^C

However, it’s connected to the WGW we created earlier.

ubuntu@ip-10-10-11-10:~$ sudo wg show
interface: peer1
  public key: Jt1zAJD6W2BZgOwtUsNY2KrMO0oRfUmfAEZGNEUZKiQ=
  private key: (hidden)
  listening port: 33174

peer: XYy8e5EKtE1F0fwwMgr792/9noYs53uRZBX5O3XJ4Eg=
  endpoint: 64.16.243.3:5107
  allowed ips: 172.27.0.0/24
  latest handshake: 14 seconds ago
  transfer: 124 B received, 596 B sent
  persistent keepalive: every 1 second

Peer in Cloud B

Similarly, this Droplet instance runs an apache server but only allows inbound SSH traffic.

As a result, it’s unreachable from the public internet.

user@localhost ~ % ping 161.35.112.164
PING 161.35.112.164 (161.35.112.164): 56 data bytes
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
^C
--- 161.35.112.164 ping statistics ---
3 packets transmitted, 0 packets received, 100.0% packet loss
user@localhost ~ % curl 161.35.112.164
^C

However, it’s connected to the WGW we created earlier.

root@ubuntu-s-1vcpu-512mb-10gb-nyc1-01:~# sudo wg show
interface: peer2
  public key: eAvskX/cBw10DpxPPcvItsFcBr2meAKOVgwFjysZnF4=
  private key: (hidden)
  listening port: 33951

peer: XYy8e5EKtE1F0fwwMgr792/9noYs53uRZBX5O3XJ4Eg=
  endpoint: 64.16.243.3:5107
  allowed ips: 172.27.0.0/24
  latest handshake: 4 seconds ago
  transfer: 124 B received, 308 B sent
  persistent keepalive: every 1 second

Cross Cloud Boundary

Despite of the firewall rule configs in the respective environments, Peer 1 is able to talk to Peer 2 over the WireGuard subnet. From Peer 1

ubuntu@ip-10-10-11-10:~$ curl 172.27.0.3
<!DOCTYPE html>


        I am the Droplet Peer in DigitalOcean

From Peer 2

root@ubuntu-s-1vcpu-512mb-10gb-nyc1-01:~# curl 172.27.0.2
<!DOCTYPE html>


        I am the EC2 Peer in AWS

This is readily extensible to peers running web services in various environments.

Use Case 2: Private Access to Other Telnyx Services

If a WGW is created with enable_sip_trunking, the WGW will enable routing for all Telnyx public API endpoints.

On the peer config, additional routes are added under AllowedIPs.

[Interface]
PrivateKey = XXX
Address = 172.27.0.2/32

[Peer]
PublicKey = jSSaLXXVEzYUM8N8IM+65YuuScL+Sf2DytZCdLhFSGo=
AllowedIPs = 172.27.0.0/24, 64.16.250.10/32, 64.16.250.11/32, 64.16.250.13/32, 103.115.244.145/32, 103.115.244.146/32, 185.246.41.140/32, 185.246.41.141/32, 192.76.120.10/32, 192.76.120.11/32, 192.76.120.31/32, 64.16.226.0/24, 64.16.227.0/24, 64.16.228.0/24, 64.16.230.0/24, 64.16.248.0/24, 64.16.249.0/24, 50.114.144.0/21, 185.246.41.128/25, 103.115.244.128/25, 64.16.239.98/32, 64.16.239.39/32, 64.16.239.82/32, 64.16.224.44/32
Endpoint = 64.16.243.15:5016
PersistentKeepalive = 1

As a result, traffic between a connected peer to Telnyx API, SIP, and Storage services will flow through the WGW (172.27.0.1) onto the Telnyx network as demonstrated below.

user@localhost ~ % traceroute sip.telnyx.com
traceroute to sip.telnyx.com (192.76.120.10), 64 hops max, 40 byte packets
 1  172.27.0.1 (172.27.0.1)  6.708 ms  7.726 ms  7.133 ms
 2  *^C
user@localhost ~ % traceroute api-direct.telnyx.com
traceroute to api-direct.telnyx.com (64.16.224.44), 64 hops max, 40 byte packets
 1  172.27.0.1 (172.27.0.1)  7.673 ms  6.239 ms  6.488 ms
 2  *^C
user@localhost ~ % traceroute us-central-1.telnyxcloudstorage.com
traceroute to us-central-1.telnyxcloudstorage.com (64.16.239.39), 64 hops max, 40 byte packets
 1  172.27.0.1 (172.27.0.1)  6.885 ms  6.898 ms  6.621 ms
 2  * *^C
user@localhost ~ % aws s3api list-buckets --profile "*.telnyxcloudstorage.com" --endpoint-url https://us-central-1.telnyxcloudstorage.com
{
    "Buckets": [
        {
            "Name": "bucket1",
            "CreationDate": "2024-03-26T17:54:09.271000+00:00"
        },
        {
            "Name": "bucket2",
            "CreationDate": "2024-03-26T16:51:51.967000+00:00"
        },
        {
            "Name": "bucket3",
            "CreationDate": "2023-11-29T13:50:59.837000+00:00"
        }
    ],
    "Owner": {
        "DisplayName": "xxx",
        "ID": "xxx"
    }
}

This arrangement is extremely useful in the case where we have to lock down public routing in the event of an extreme DDoS attack.

Use Case 3: Cross-Region Network

The previous architecture can be extended to the following one.

In this example ---

Site A is Telnyx Ashburn
Site B is Telnyx Amsterdam
Cloud A is AWS
Cloud B is Digital Ocean

Traffic between the two peers ride the Telnyx backbone between Ashburn and Amsterdam. Coming Soon.

Other use cases

See Global IP (Coming Soon)
See Internet Gateway (IGW) Guide
See Private Wireless Gateway (PGW) Guide (Coming Soon)

Costs

MRC for each WGW instance is $10.
Connected Peers are free of charge.

API References

WGW
Peers

Linux Configuration

Source: https://developers.telnyx.com/docs/network/wireguard-peer-config/linux.md

Prerequisite

You come from here and have a .conf file ready.

Step 1: Install WireGuard

ubuntu@ip-10-10-11-10:~$ sudo apt install wireguard

Step 2: Bring up the Interface

Assuming the correct config file is located at /etc/wireguard/peer1.conf

ubuntu@ip-10-10-11-10:~$ sudo wg-quick up peer1
[#] ip link add peer1 type wireguard
[#] wg setconf peer1 /dev/fd/63
[#] ip -4 address add 172.27.0.2/32 dev peer1
[#] ip link set mtu 8921 up dev peer1
[#] ip -4 route add 172.27.0.0/24 dev peer1

Step 3: Validating and Testing

ubuntu@ip-10-10-11-10:~$ sudo wg show
interface: peer1
  public key: Jt1zAJD6W2BZgOwtUsNY2KrMO0oRfUmfAEZGNEUZKiQ=
  private key: (hidden)
  listening port: 43548

peer: XYy8e5EKtE1F0fwwMgr792/9noYs53uRZBX5O3XJ4Eg=
  endpoint: 64.16.243.3:5107
  allowed ips: 172.27.0.0/24
  latest handshake: 1 minute, 28 seconds ago
  transfer: 92 B received, 2.86 KiB sent
  persistent keepalive: every 1 second

If another peer is connected to the network, it should be pingable.

ubuntu@ip-10-10-11-10:~$ ping 172.27.0.3
PING 172.27.0.3 (172.27.0.3) 56(84) bytes of data.
64 bytes from 172.27.0.3: icmp_seq=1 ttl=63 time=25.8 ms
64 bytes from 172.27.0.3: icmp_seq=2 ttl=63 time=25.6 ms
64 bytes from 172.27.0.3: icmp_seq=3 ttl=63 time=25.5 ms
^C
--- 172.27.0.3 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2004ms
rtt min/avg/max/mdev = 25.493/25.610/25.751/0.106 ms

Next Steps

WireGuard Gateway (WGW) Guide outlines many use cases that may be valuable to you.

macOS Configuration

Source: https://developers.telnyx.com/docs/network/wireguard-peer-config/macos.md

Prerequisite

You come from here and have a .conf file ready.

Step 1: Install WireGuard Client

From here, choose and install the macOS client.

Step 2: Create a Tunnel

“Import Tunnel(s) from File…”

“Activate”

At this point, it should show “Status: Active”

Step 3: Validating and Testing

A connected peer should be pingable.

user@macbook-pro wireguard % ping 172.27.0.3
PING 172.27.0.3 (172.27.0.3): 56 data bytes
64 bytes from 172.27.0.3: icmp_seq=0 ttl=63 time=35.006 ms
64 bytes from 172.27.0.3: icmp_seq=1 ttl=63 time=32.528 ms
64 bytes from 172.27.0.3: icmp_seq=2 ttl=63 time=33.376 ms
^C
--- 172.27.0.3 ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 32.528/33.637/35.006/1.028 ms

Next Steps

WireGuard Gateway (WGW) Guide outlines many use cases that may be valuable to you.

Windows Configuration

Source: https://developers.telnyx.com/docs/network/wireguard-peer-config/windows.md

Prerequisite

You come from here and have a .conf file ready.

Step 1: Install WireGuard Client

From here, choose and install the Windows Installer.

Step 2: Create a Tunnel

“Import Tunnel(s) from File…”

“Activate”

At this point, it should show “Status: Active”

Step 3: Validating and Testing

You can try pinging to/from a connected peer. If that does not work you can also try to set up a barebones http server and hit it from the connected peer (or vice versa). An example barebones server in python:

import socket

SERVER_HOST = "0.0.0.0"
SERVER_PORT = 8000

server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
server_socket.bind((SERVER_HOST, SERVER_PORT))
server_socket.listen(1)

while True:
    client_connection, client_address = server_socket.accept()
    request = client_connection.recv(1024).decode()
    response = 'HTTP/1.0 200 OK\n\nIt works!'
    client_connection.sendall(response.encode())
    client_connection.close()

Run the server in one peer (python3 server.py - assuming you saved the above example in a file named server.py) and reach it with a client / browser from the other peer:

$ curl --location 'http://172.27.0.4:8000/'
It works!

Next Steps

WireGuard Gateway (WGW) Guide outlines many use cases that may be valuable to you.

Internet Gateway (IGW)

Source: https://developers.telnyx.com/docs/network/gateways/internet-gateway.md

This is a beta feature

Introduction

Internet Gateway (IGW) is an element that routes traffic between your Telnyx network and the internet. It is intended to be used with certain other elements.

Creating an IGW

Step 1: Create a Network

Follow this guide.

Step 2: Check for Coverage

Follow this guide. Use filter[available_services][contains]=public_internet_gateway to look for a desired site at which to deploy the IGW. frankfurt-de is chosen for the subsequent steps.

Step 3: Create an IGW

Using the network created from Step 1 and the chosen region from Step 2, create the IGW. Once an IGW is created on a specific network, it cannot be “migrated” to another one; it needs to be recreated on the other network. Double check the correct network_id is used in the following API request.

POST /v2/public_internet_gateways HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 125

{
  "network_id": "5647b6cf-b204-42d6-9c63-f2fd12253113",
  "name": "my_first_igw",
  "region_code": "frankfurt-de"
}

It’s not yet ready to be used immediately after the creation since its status is provisioning.

{
    "data": {
        "created_at": "2024-08-01T14:36:39.938006Z",
        "region_code": "frankfurt-de",
        "name": "my_first_igw",
        "network_id": "5647b6cf-b204-42d6-9c63-f2fd12253113",
        "id": "06d65677-f1aa-43b6-8a6c-4f1abfe93754",
        "status": "provisioning",
        "updated_at": "2024-08-01T14:36:41.497785Z",
        "record_type": "public_internet_gateway",
        "public_ip": "64.16.243.172"
    }
}

Step 4: Wait for Status Transition

The expected time for status to transition to provisioned is approximately 10 minutes. You can poll the IGW to check for status.

GET /v2/public_internet_gateways/{{igw_uuid}} HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

Use Cases

Use Case 1: Pure play VPN

Internet Gateway (IGW) can be used with WireGuard Gateway (WGW) to create a simple VPN service.

Set up an IGW
Set up a WGW and a peer.
On the peer, amend its config with:
- DNS — choose your resolver. In the following example, 8.8.8.8 is chosen.
- AllowedIPs — append with 0.0.0.0/0 so that reachability is beyond the private subnet.

Here is an example config of the peer.

[Interface]
PrivateKey = XXX
Address = 172.27.0.2/32
DNS = 8.8.8.8

[Peer]
PublicKey = YYY
AllowedIPs = 172.27.0.0/24, 0.0.0.0/0
Endpoint = 64.16.243.7:5022
PersistentKeepalive = 1

Deactivate and reactivate your WireGuard tunnel. You should see the IGW’s public IP showing up when you query what your public IP is.

user@localhost ~ % dig -4 TXT +short o-o.myaddr.l.google.com @ns1.google.com
"64.16.243.172"

Use Case 2: IGW + Private Wireless Gateway (PWG)

Coming Soon.

Costs

The monthly recurring cost (MRC) for each instance of IGW is $50.
Traffic is not currently metered in beta phase. We will meter traffic in GA phase.

API References

Private Wireless Gateway (PGW)

Source: https://developers.telnyx.com/docs/network/gateways/private-wireless-gateway.md

Introduction

Private Wireless Gateway (PGW) is an element that routes traffic between a group of Telnyx SIMs and other network elements. Refer to this guide for more information on PGW.

Creating a PGW

Step 1: Create a Network

Follow this guide.

Step 2: Check for Coverage

Follow this guide. Use filter[available_services][contains]=private_wireless_gateway to look for a desired site at which to deploy the WGW. Currently, Ashburn, VA is the only supported site. We are working on making more sites available.

Step 3: Create a PGW

Once a PGW is created on a specific network, it cannot be “migrated” to another one; it needs to be recreated on the other network. Double check the correct network_id is used in the following API request.

POST /v2/private_wireless_gateways HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 115

{
  "network_id": "f09e6854-fdef-4581-b3bc-63c2008fc4b5",
  "name": "pgw-08160937",
  "region_code": "ashburn-va"
}

It’s not yet ready to be used immediately after the creation since its status is provisioning.

{
    "data": {
        "assigned_resources": [
            {
                "count": null,
                "record_type": "sim_card_group"
            }
        ],
        "created_at": "2024-08-16T14:37:47Z",
        "id": "2280aa63-b9b8-4d8a-867a-ff153e5ec422",
        "ip_range": "100.64.199.0/24",
        "name": "pgw-08160937",
        "network_id": "f09e6854-fdef-4581-b3bc-63c2008fc4b5",
        "record_type": "private_wireless_gateway",
        "region_code": "ashburn-va",
        "status": {
            "error_code": null,
            "error_description": null,
            "value": "provisioning"
        },
        "updated_at": "2024-08-16T14:37:47Z"
    }
}

Step 4: Wait for Status Transition

The expected time for status.value to transition to provisioned is approximately 15 minutes. You can poll the PGW to check for status.

GET /v2/private_wireless_gateways/2280aa63-b9b8-4d8a-867a-ff153e5ec422 HTTP/1.1
Host: api.telnyx.com
Authorization: Bearer XXX

Step 5: Attach a SIM Group

The PGW is of little use when there is no SIMs are attached to it. Individual SIM must be added to a SIM group which then can be attached to the PGW. This is easily accomplished on the Mission Control Portal. PGW will show the SIM group after a successful attachment.

{
    "data": {
        "assigned_resources": [
            {
                "count": 1,
                "record_type": "sim_card_group"
            }
        ],
        "created_at": "2024-08-16T14:37:47Z",
        "id": "2280aa63-b9b8-4d8a-867a-ff153e5ec422",
        "ip_range": "100.64.199.0/24",
        "name": "pgw-08160937",
        "network_id": "f09e6854-fdef-4581-b3bc-63c2008fc4b5",
        "record_type": "private_wireless_gateway",
        "region_code": "ashburn-va",
        "status": {
            "error_code": null,
            "error_description": null,
            "value": "provisioned"
        },
        "updated_at": "2024-08-16T15:08:15Z"
    }
}

Use Cases

In the following examples, abbreviations are consistently used for brevity.

PWG = Private Wireless Gateway
WGW = WireGuard Gateway
IGW = Internet Gateway
VXC = Virtual Cross Connect

Use Case 1: PWG + WGW

We will construct this architecture which is useful when

Traffic to and from SIMs needs to be segmented and private, and
They do not need high bandwidth connection back to your internal service.

In the following example

The connected device is an iPhone.
It only has access to the peers attached to the WGW; there exists no default route for them.
Internal Service Peer is a Droplet on DigitalOcean that runs an toy Apache web server.
Admin Peer is a local host.

Detailed WGW and Peer setup guide can be found here. On both peers, ensure that both the WGW subnet and the PGW subnet are on the AllowedIPs of the [Peer] config.

[Peer]
PublicKey = XXX
AllowedIPs = 172.27.0.0/24, 100.64.199.0/24
Endpoint = XXX
PersistentKeepalive = XXX

From the internal service peer, we can see there is a route to the iPhone.

root@ubuntu-s-1vcpu-512mb-10gb-nyc1-01:~# traceroute 100.64.199.1
traceroute to 100.64.199.1 (100.64.199.1), 64 hops max
 172.27.0.1  21.591ms  21.000ms  20.677ms
 *  *  *
 *  *  *
 *  *  *
 100.64.199.1  885.269ms  179.245ms  171.923ms

From the iPhone, it has access to the internal service peer.

Use Case 2: PWG + WGW + IGW

The above architecture lacks a crucial functionality --- internet reachability. Though a workaround can be constructed by using one of the peers as an exit node for all default traffic, it’s far better to attach an IGW to the network.

Follow the procedure outlined in this guide to set up an IGW on the same network. At this point, the iPhone has internet reachability in addition to the WGW subnet and the PGW subnet.

In the above screenshots,

the iPhone’s wifi is turned off
its “Default Gateway IP” is 100.64.199.1 which is that of the PGW
its “External IP” is 64.16.243.172 which is that of the IGW
it can ping google.com

Roundtrip ping time is high since in this example, the PGW is in Ashburn US while the IGW is in Frankfurt DE.

Use Case 3: PWG + WGW + IGW + VXC

Currently, the PWG + WGW + IGW + VXC combination only works when WGW, IGW, and VXC are at the Frankfurt Site. We are working on expanding the coverage so it will work universally across all Telnyx sites. In the case where the user’s internal services reside in a cloud provider, the architecture can be augmented yet again. In this case, a VXC can be attached to the network to accommodate this scenario. In the following example, we will establish

a VXC from AWS eu-central-1
an EC2 in AWS eu-central-1 running a toy Apache server.

For detailed VXC guide on AWS and other providers, please refer to this collection of guides

In AWS’s VPC, we can see the routes from Telnyx’s public APIs AND the SIMs’ private IP ranges are advertised and propagated.

This is also validated by the traceroute output from within the EC2 instance. Latency is high as expected since the EC2 is in Frankfurt while the device is attached to a PGW in Ashburn.

ubuntu@ip-10-10-11-9:~$ traceroute 100.64.199.1
traceroute to 100.64.199.1 (100.64.199.1), 64 hops max
 169.254.237.21  0.916ms  1.091ms  1.079ms
 169.254.69.2  0.911ms  0.827ms  0.816ms
 169.254.69.1  1.398ms  1.347ms  1.338ms
 100.100.100.1  1.833ms  1.782ms  1.769ms
 100.65.72.1  120.938ms  120.001ms  119.756ms
 64.16.254.219  119.999ms  119.879ms  119.924ms
 64.16.254.71  119.758ms  119.691ms  120.006ms
 *  *  *
 169.254.208.167  119.488ms  119.552ms  119.599ms
 172.22.25.82  120.438ms  120.072ms  119.640ms
 100.64.199.1  274.343ms  252.264ms  246.660ms

Lastly, validate the connection from the device to EC2. Since the EC2 runs a toy Apache server, open up the HTTP port 80 for the SIM subnet.

From the iPhone, the server is clearly accessible via private IP.

Costs

The monthly recurring cost (MRC) for each instance of PGW is $100.
Additional costs on SIM and data are applicable as well. Consult this guide for more detail.

API References

VXC Introduction

Source: https://developers.telnyx.com/docs/network/vxc/intro.md

This guide first gives an overview of the product’s availability, costs, and the general API structure. Subsequently, it branches into cloud provider specific guides. The reader should only concern themselves with the section about the cloud provider that’s relevant to their use case.

Coverage & Availability

Source: https://developers.telnyx.com/docs/network/vxc/coverage.md

Refer to the coverage API to ensure the desired resource is offered at the desired region.

Pricing

Source: https://developers.telnyx.com/docs/network/vxc/cost.md

You will be charged by Telnyx AND your cloud provider. Telnyx charges an MRC for each VXC instance according to the following schedule, which may change at our discretion according to the general T&C. We can neither interpret nor advise how your cloud provider may charge your account. Please consult your cloud provider’s documentation.

AWS

Virtual Cross Connects	Monthly Recurring Charge (USD)
50 Mbps	100
100 Mbps	125
200 Mbps	150
300 Mbps	175
400 Mbps	200
500 Mbps	225
1 Gbps	450

GCP

Virtual Cross Connects	Monthly Recurring Charge (USD)
50 Mbps	100
100 Mbps	125
200 Mbps	150
300 Mbps	175
400 Mbps	200
500 Mbps	225
1 Gbps	450

Azure

Virtual Cross Connects	Monthly Recurring Charge (USD)
50 Mbps	200
100 Mbps	250
200 Mbps	300
300 Mbps	400
400 Mbps	500
500 Mbps	600
1 Gbps	1000

VXC API

Source: https://developers.telnyx.com/docs/network/vxc/api.md

The API resource in question is /v2/virtual_cross_connects. The following group of parameters needs to be provided regardless of the cloud provider.

Parameter	Value
`network_id`	A VXC must be associated with a network. If no network exists on your account, you need to create one first.
`name`	Human readable text; something meaningful to you.

The rest of the parameters are cloud provider specific. Please consult the subsequent sections.

AWS Direct Connect

Source: https://developers.telnyx.com/docs/network/vxc/aws.md

Architecture

We will construct the following architecture:

Prerequisites

VPC

This step is performed on AWS.

⚠️ Note: Ensure the intended region is selected. In this example, we are using eu-central-1 as the region.

Parameter	Value
Resources to create	VPC only
IPv4 CIDR block	IPv4 CIDR manual input
IPv4 CIDR	RFC1918, e.g. 10.10.11.0/24
IPv6 CIDR block	No IPv6 CIDR block
Tenancy	Default

Virtual Private Gateway

This step is performed on AWS. Create and attach a virtual private gateway to the VPC created.

⚠️ Note: Ensure the intended region is selected. In this example, we are using eu-central-1 as the region.

⚠️ Note: Amazon default ASN value is 64512. You will need this value for VXC creation. Next, attach the virtual private gateway to the VPC created in the first step.

The state of the virtual private gateway will go from “Detached” to “Attaching” and finally “Attached”.

VPC Route Table

This step is performed on AWS.

Internet Gateway

This step is performed on AWS. This is optional. Create and attach an internet gateway to the VPC created.

Subnet

This step is performed on AWS. Assuming you don’t have a subnet setup — Choose the VPC created. Subnet CIDR block should be chosen from within the VPC block.

EC2

This step is performed on AWS. Assuming you don’t have an EC2 instance — spin one up in the same region. Assign the VPC and Subnet created previously. Enable public IP on the instance so you can ssh into it.

Account ID

This step is performed on AWS. ⚠️ You would need this number when you create the Telnyx VXC later.

Telnyx Network

This step is performed on Telnyx. If you don’t have a network created already, you may follow this guide to create one.

Procedure

Create a VXC resource

This step is performed on Telnyx.

request

POST /v2/virtual_cross_connects HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 286

{
    "network_id": "314ae4ed-04f0-4111-be40-240beb7fdcf0",
    "name": "xd-frankfurt-vxc-aws",
    "cloud_provider": "aws",
    "cloud_provider_region": "eu-central-1",
    "primary_cloud_account_id": "YYY",
    "bgp_asn": 64512,
    "bandwidth_mbps": 50
}

Parameter	Value
`cloud_provider`	`aws`
`cloud_provider_region`	Match what you selected on the AWS
`primary_cloud_account_id`	AWS account ID from the last step
`bgp_asn`	AWS’s bgp asn which is 64512
`bandwidth_mbps`	Chosen from available bandwidth of the VXC coverage API

Take note of the VXC id returned in the response.

Direct Connect

This step is performed on AWS. If you haven’t accepted the connection from your AWS account within 1 hour of the VXC creation, the VXC would be deleted and you will have to start over.

Enable Primary Connection

This step is performed on Telnyx. The connection must be enabled to be used.

request

PATCH /v2/virtual_cross_connects/:vxc_uuid HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 31

{
    "primary_enabled": true
}

At this point, the connection on AWS will show as “available”.

Virtual Interface

This step is performed on AWS. The connection created above needs to have an interface to which to connect.

Interface Parameters

Parameter	Value
Type	Private
Connection	Choose the Direct Connection you accepted previously.
Virtual interface owner	My AWS account
Gateway Type	Virtual Private Gateway and select the one you created in Prerequisite – AWS → Virtual Private Gateway
BGP ASN	63440 - Telnyx ASN
Your router peer IP - optional	`primary_telnyx_ip`
Amazon router peer IP - optional	`primary_cloud_ip`
BGP authentication key - optional	`primary_bgp_key`

Lastly you should see the following – the interface is “available”.

Validate Connection

This step is performed on AWS. ssh into your EC2 instance and either ping or traceroute to one of the IP in the route table of the VPC. You can see the route went over the VXC instead of the public internet.

Google Cloud Interconnect

Source: https://developers.telnyx.com/docs/network/vxc/gcp.md

Architecture

We will construct the following architecture on Google Cloud.

Prerequisites

VLAN Attachment

This step is performed on Google

Parameters:

“Partner Interconnect Connection”
“Set up unencrypted Interconnect”

“Network”: Choose the one you are connecting from
“Region”: Choose the one that there is a Telnyx PoP in proximity
“MTU”: 8896

Create a router or choose an existing one.

Telnyx Network

This step is performed on Telnyx. If you don’t have a network created already, you may follow this guide to create one.

Procedure

Create a VXC resource

This step is performed on Telnyx.

POST /v2/virtual_cross_connects HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 286

{
    "network_id": "a843547c-3f08-4a7e-8a4b-270c3ffb13f2",
    "name": "xd-frankfurt-vxc-gcp",
    "cloud_provider": "gce",
    "cloud_provider_region": "europe-west3",
    "primary_cloud_account_id": "xxxx/europe-west3/2",
    "bgp_asn": 16550,
    "bandwidth_mbps": 50
}

Activate Connection

This step is performed on Google.

“Peer ASN”: 63440 (Telnyx) “MD5 Authentication”: primary_bgp_key

Update BGP Peering

This step is performed on Telnyx. At this point, the connection is “Down”. We need to take the Google assigned GBP IPs and set them on the VXC.

Use the PATCH method.

primary_cloud_ip — “Cloud Router BGP IP” or “Remote IP” in the “Troubleshooting” page
primary_telnyx_ip — “BGP peer IP” or “Local IP”in the “Troubleshooting” page

PATCH /v2/virtual_cross_connects/:vxc_uuid HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 31

{
    "primary_enabled": true,
    "primary_cloud_ip": "169.254.131.250/29",
    "primary_telnyx_ip": "169.254.131.249/29"
}

At this point, on Google, it will show the “Status” as “Up”

Validate Connection

This step is performed on Google.

Under VPC networks, you should see the routes advertised over the cloud router created.
You can also ssh in one of your instances in the same network and perform a traceroute.

xxx@instance-20240503-154050:~$ traceroute sip.telnyx.com
traceroute to sip.telnyx.com (192.76.120.10), 30 hops max, 60 byte packets
* * *
100.65.72.1 (100.65.72.1)  4.393 ms  4.367 ms  4.349 ms
64.16.254.51 (64.16.254.51)  114.732 ms  114.715 ms  114.698 ms
64.16.247.105 (64.16.247.105)  114.903 ms  114.877 ms  114.860 ms
192.76.120.160 (192.76.120.160)  114.843 ms  114.825 ms  114.807 ms
sip.telnyx.com (192.76.120.10)  114.857 ms  114.064 ms  114.038 ms

Azure ExpressRoute

Source: https://developers.telnyx.com/docs/network/vxc/azure.md

Architecture

We will construct the following architecture.

Prerequisites

Create ExpressRoute Circuit

This step is performed on Azure.

Parameter	Value
Region	Choose the matching available region from the VXC coverage API
Port Type	Provider
Provider	Equinix
Peering location	matching available region from the VXC coverage API
Bandwidth	Choose the available bandwidth from the VXC coverage API
SKU	Standard

Choose the rest of the parameters at your own discretion.

At the end of this step, the “Provider status” should say “Not provisioned”.

Telnyx Network

This step is performed on Telnyx. If you don’t have a network created already, you may follow this guide to create one.

Procedure

Create a VXC resource

This step is performed on Telnyx.

request

POST /v2/virtual_cross_connects HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 286

{
    "network_id": "{{you network UUID}}",
    "name": "my-first-azure-vxc",
    "cloud_provider": "azure",
    "cloud_provider_region": "Frankfurt",
    "primary_cloud_account_id": "xxxxxx",
    "bgp_asn": 12076
}

Parameter	Value
`cloud_provider`	`azure`
`cloud_provider_region`	Choose the matching region from the ExpressRoute circuit
`primary_cloud_account_id`	”Service key” on the ExpressRoute created previously
`bgp_asn`	Azure’s bgp asn which is 12076

Take note of the following info in the response; you will need it later.

id
primary_cloud_ip
primary_bgp_key

Enable Primary Connection

This step is performed on Telnyx.

request

PATCH /v2/virtual_cross_connects/:vxc_uuid HTTP/1.1
Host: api.telnyx.com
Content-Type: application/json
Authorization: Bearer XXX
Content-Length: 31

{
    "primary_enabled": true
}

You must make sure the VXC status is provisioned before proceeding to the next step. You can poll the status using GET request on the specific VXC.

Azure Private Peering

This step is performed on Azure. “Provider status” must show “Provisioned” before performing this step.

Parameter	Value
Peer ASN	Telnyx’s BGP ASN which is 63440
Subnets	IPv4
IPv4 Primary subnet	Choose the /30 block that includes `primary_cloud_ip`
IPv4 Secondary subnet	Choose the next /30 block
VLAN ID	Choose any number from a valid VLAN range
Shared key	primary bgp key
Public IP address	Create new
Public IP address SKU	Standard

After saving, you may need to wait for some time before performing the next step.

At this point, you should see Telnyx IPs advertised in the result after you click into “View route table.”

At this point, you are all set. Perform the following steps only if you are trying to test things out before putting it into your own production environment.

Virtual Network

Parameters	Value
Region	Match that of the virtual network created from the previous step

Next, add a Gateway subnet. Keep all parameters as default.

Virtual Network Gateways

Parameters	Value
Name	Something meaningful to you
Region	Match that of the virtual network created from the previous step
Gateway type	Express Route
SKU	Standard
Virtual network	Choose the one created from the previous step
Public IP address	Create new
Public IP address SKU	Standard

The gateway creation will take a while; upward of 20 minutes. In the meantime, you can proceed to the following step.

Virtual Machines

Parameters	Value
Region	Match that of the virtual network created from the previous step

Parameters	Value
Virtual network	Choose the one created from the previous step

You can keep the rest default or choose at your discretion.

Add Gateway Connection

This step is performed on Azure. The Virtual Gateway you created must be successfully deployed before this step is performed.

Parameters	Value
Connection type	Express Route

Parameters	Value
Virtual network gateway	Choose the one created from the previous step
ExpressRoute circuit	Choose the one created from the previous step
Routing weight	0

Validate Connection

This step is performed on Azure. Ensure all of the following are successfully deployed:

ExpressRoute
Virtual network
Virtual network gateway & connection
Virtual machine

SSH into the VM and perform a traceroute to sip.telnyx.com and sip.telnyx.eu. You can see the next hop is the next hop indicated on the Azure Private Peering under the express route.

API Reference (Compute)

Regions

List all Regions: List all regions and the interfaces that region supports

Networks

List all Networks: List all Networks.
Create a Network: Create a new Network.
Retrieve a Network: Retrieve a Network.
Update a Network: Update a Network.
Delete a Network: Delete a Network.
Get Default Gateway status.: Get Default Gateway status.
Create Default Gateway.: Create Default Gateway.
Delete Default Gateway.: Delete Default Gateway.
List all Interfaces for a Network.: List all Interfaces for a Network.

WireGuard Interfaces

List all WireGuard Interfaces: List all WireGuard Interfaces.
Create a WireGuard Interface: Create a new WireGuard Interface. Current limitation of 10 interfaces per user can be created.
Retrieve a WireGuard Interfaces: Retrieve a WireGuard Interfaces.
Delete a WireGuard Interface: Delete a WireGuard Interface.
List all WireGuard Peers: List all WireGuard peers.
Create a WireGuard Peer: Create a new WireGuard Peer. Current limitation of 5 peers per interface can be created.
Retrieve the WireGuard Peer: Retrieve the WireGuard peer.
Update the WireGuard Peer: Update the WireGuard peer.
Delete the WireGuard Peer: Delete the WireGuard peer.
Retrieve Wireguard config template for Peer: Retrieve Wireguard config template for Peer

Private Wireless Gateways

Get all Private Wireless Gateways: Get all Private Wireless Gateways belonging to the user.
Create a Private Wireless Gateway: Asynchronously create a Private Wireless Gateway for SIM cards for a previously created network. This operation may take several minutes so you can check the P…
Get a Private Wireless Gateway: Retrieve information about a Private Wireless Gateway.
Delete a Private Wireless Gateway: Deletes the Private Wireless Gateway.

Public Internet Gateways

List all Public Internet Gateways: List all Public Internet Gateways.
Create a Public Internet Gateway: Create a new Public Internet Gateway.
Retrieve a Public Internet Gateway: Retrieve a Public Internet Gateway.
Delete a Public Internet Gateway: Delete a Public Internet Gateway.

Virtual Cross Connects

List all Virtual Cross Connects: List all Virtual Cross Connects.
Create a Virtual Cross Connect: Create a new Virtual Cross Connect. For AWS and GCE, you have the option of creating the primary connection first and the secondary connection later…
Retrieve a Virtual Cross Connect: Retrieve a Virtual Cross Connect.
Update the Virtual Cross Connect: Update the Virtual Cross Connect. Cloud IPs can only be patched during the created state, as GCE will only inform you of your generated IP once th…
Delete a Virtual Cross Connect: Delete a Virtual Cross Connect.
List Virtual Cross Connect Cloud Coverage: List Virtual Cross Connects Cloud Coverage. This endpoint shows which cloud regions are available for the location_code your Virtual Cross Connect…

Global IPs

List all Global IPs: List all Global IPs.
Create a Global IP: Create a Global IP.
Retrieve a Global IP: Retrieve a Global IP.
Delete a Global IP: Delete a Global IP.
List all Global IP Allowed Ports: List all Global IP Allowed Ports
Global IP Assignment Health Check Metrics
List all Global IP assignments: List all Global IP assignments.
Create a Global IP assignment: Create a Global IP assignment.
Update a Global IP assignment: Update a Global IP assignment.
Delete a Global IP assignment: Delete a Global IP assignment.
Global IP Assignment Usage Metrics
List all Global IP Health check types: List all Global IP Health check types.
List all Global IP health checks: List all Global IP health checks.
Create a Global IP health check: Create a Global IP health check.
Retrieve a Global IP health check: Retrieve a Global IP health check.
Delete a Global IP health check: Delete a Global IP health check.
Global IP Latency Metrics
List all Global IP Protocols: List all Global IP Protocols
Global IP Usage Metrics

Compute llms.txt

Overview llms.txt

⌘I

​Telnyx Compute — Full Documentation

​Overview

​Edge Compute

​Start building

​Functions

​Functions

​The platform around your functions

​Languages

​Where your code runs

​Resources

​Quickstart

​Prerequisites

​1. Install the CLI

​2. Authenticate

​3. Create a function

​4. Ship

​5. Call it

​Next Steps

​Best Practices

​Configuration

​Keep Secrets Out of Code

​Budget for the Platform Timeout

​Name Functions for Their URL

​Performance

​Initialize Once, at Module Scope

​Keep Cold Starts Small

​Cache Expensive Reads in KV

​Put State Where It Belongs

​Reliability

​Make Handlers Idempotent

​Keep the Health Endpoint Fast

​Catch Everything at the Top of the Handler

​Time Out and Retry Outbound Calls

​Security

​Observability

​Next Steps

​AI Assistants and Edge Compute

​What you’ll build

​Prerequisites

​Key concepts

​Single function, two callbacks

​Webhook signature verification

​Dynamic variables response format

​Timeout

​Step 1: Scaffold the function

​Step 2: Store the public key as a secret

​Step 3: Write the handler

​Step 4: Ship the function

​Step 5: Configure the AI Assistant

​Dynamic variables webhook

​Template variables in the assistant

​Webhook tool

​Step 6: Test end-to-end

​Tips and gotchas

​Choosing body-shape vs path-based dispatch

​Consider a higher webhook timeout

​Always verify signatures

​Ship takes a few minutes

​Secrets require re-shipping

​The dynamic_variables wrapper is mandatory

​Next steps

​Local Development

​Run and test, by language

​Testing

​Framework servers

​Bindings and secrets

​Deploy

​Next Steps

​Configuration

​func.toml

​[edge_compute] — identity

​[env_vars] — environment variables

​[[secrets]] — secret bindings

​[telnyx] — Telnyx API binding

​[storage.kv.] — KV namespace binding

​[storage.cloudstorage.] — Cloud Storage bucket binding

​telnyx.toml

​Configured outside the manifest

​Ship-time validation

​Related

Telnyx Compute — Full Documentation

Overview

Edge Compute

Start building

Functions

Functions

The platform around your functions

Languages

Where your code runs

Resources

Quickstart

Prerequisites

1. Install the CLI

2. Authenticate

3. Create a function

4. Ship

5. Call it

Next Steps

Best Practices

Configuration

Keep Secrets Out of Code

Budget for the Platform Timeout

Name Functions for Their URL

Performance

Initialize Once, at Module Scope

Keep Cold Starts Small

Cache Expensive Reads in KV

Put State Where It Belongs

Reliability

Make Handlers Idempotent

Keep the Health Endpoint Fast

Catch Everything at the Top of the Handler

Time Out and Retry Outbound Calls

Security

Observability

Next Steps

AI Assistants and Edge Compute

What you’ll build

Prerequisites

Key concepts

Single function, two callbacks

Webhook signature verification

Dynamic variables response format

Timeout

Step 1: Scaffold the function

Step 2: Store the public key as a secret

Step 3: Write the handler

Step 4: Ship the function

Step 5: Configure the AI Assistant

Dynamic variables webhook

Template variables in the assistant

Webhook tool

Step 6: Test end-to-end

Tips and gotchas

Choosing body-shape vs path-based dispatch

Consider a higher webhook timeout

Always verify signatures

Ship takes a few minutes

Secrets require re-shipping

The `dynamic_variables` wrapper is mandatory

Next steps

Local Development

Run and test, by language

Testing

Framework servers

Bindings and secrets

Deploy

Next Steps

Configuration

func.toml

[edge_compute] — identity

[env_vars] — environment variables

[[secrets]] — secret bindings

[telnyx] — Telnyx API binding

[storage.kv.] — KV namespace binding

[storage.cloudstorage.] — Cloud Storage bucket binding

telnyx.toml

Configured outside the manifest

Ship-time validation

Related