# Telnyx Agent SDK — Full Documentation > Build and run stateful AI agents with scheduling, message history, SQL, and WebSockets. Complete page content for the Agent SDK section of the Telnyx developer docs (https://developers.telnyx.com). > This file: https://developers.telnyx.com/docs/development/llms/ai-agent-sdk-beta-llms-full-txt · Root index: https://developers.telnyx.com/llms.txt ## Subsections Focused per-subsection full-content files: - [Overview](https://developers.telnyx.com/docs/development/llms/ai-agent-sdk-beta-overview-llms-full-txt) - [Agent SDK](https://developers.telnyx.com/docs/development/llms/ai-agent-sdk-beta-agent-sdk-beta-llms-full-txt) - [Agent Sandboxes](https://developers.telnyx.com/docs/development/llms/ai-agent-sdk-beta-agent-sandboxes-llms-full-txt) ## Overview ### Overview > Source: https://developers.telnyx.com/docs/agent-platform.md The Agent Platform is a fully managed infrastructure for building, deploying and operating agents at scale. Agents can be built with no code at all, or with any popular framework. They are hosted on the Edge Compute platform, colocated with frontier open-weight models. Agents are governed under a centralized system of identity, access, observability and audit. Agents can be natively connected with voice, messaging, and SIM-enabled devices. They may be isolated from the internet while remaining securely connected to the user's networks via Virtual Private Cloud networking primitives. The Agent Platform comprises the following components. | Component | Description | |---|---| | [Agent Control Plane](/docs/agents) | Deploy, manage and operate all agents from the one place that ties the platform together. All agents are governed, observed and audited the same way, however they were built. | | [Agent SDK](/docs/agent-sdk) | Build agents in code, with the Telnyx harness or any popular framework. Full control over how agents reason and act, with the same hosting and operations as all other agents. | | [Agent Memory](/docs/agent-memory) | Give agents long-term memory. Every conversation picks up where the last one left off. | | [Agent Gateway](/docs/agent-gateway) | Connect agents to models, tools and other agents through one governed entry point. Every request is authenticated, authorized and audited. | | [Agent Browser](/docs/agent-browser) | Let agents use the web the way a person does, in isolated browser sessions. | | [Agent Sandboxes](/docs/edge-compute/sandboxes) | Give agents isolated computers for untrusted code, composed, controlled, and hosted at scale. | ## Next Steps - [Deploy the First Agent](/docs/agents/get-started) --- ## Agent SDK ### Overview > Source: https://developers.telnyx.com/docs/agent-sdk.md The Agent SDK's surface may change between releases, and the pages in this tab mark what is not finished yet. ## One Platform All agents are hosted on the [Agent Runtime Platform](/docs/agents/runtime-platform/edge-compute-serverless), whether they are configured or implemented in code. Its abstraction model is described there and holds for everything in this tab. ## Two Packages The Agent SDK is two packages. **The Agent Harness SDK.** `@telnyx/agent-harness`, the harness that runs the turns. [The Agent Harness SDK](/docs/agent-sdk/harness-sdk) documents it. **The Agent Runtime SDK.** `@telnyx/edge-runtime`, the runtime the harness runs on. The Agent Client SDK ships inside it as `@telnyx/edge-runtime/client`, for apps that reach an agent from outside it. [The Agent Runtime SDK](/docs/agent-sdk/runtime-sdk) documents it. Telnyx ships a managed harness as a reference implementation on the two SDKs. See [Deploy the First Agent](/docs/agents/get-started) for detail. ## Three Ways to Implement an Agent in Code From the least work to the most. Whichever way, the user is advised to understand the reference architecture in [Inside the Managed Harness](/docs/agent-sdk/inside/generated-code) first, because every class in this tab extends or replaces a part of it. **Extend the Managed Harness.** The user starts with the managed harness as it is, [exports the project](/docs/agents/cli/export) and customizes the class, which is [Extending the Managed Agent](/docs/agent-sdk/extending). **Bring a Framework.** The user brings the framework that already runs their agent, LangGraph or any other, with its own harness, or takes Telnyx's own, [The Agent Harness SDK](/docs/agent-sdk/harness-sdk), and writes the glue code against the Agent Runtime SDK. [Bring Your Own Framework](/docs/agent-sdk/examples/bring-your-own-framework) shows the glue code, and [the `Agent` class](/docs/agent-sdk/runtime-sdk) is the contract it fulfils. **Write Everything.** The user writes the framework, the harness and the glue code, on the runtime SDK alone. [Bring Your Own Framework](/docs/agent-sdk/examples/bring-your-own-framework#write-the-loop-by-hand) shows the smallest such loop. It is the most work, and the right choice only when no framework fits. ## The Stack Each layer is built on the one below it, and the pages of each layer show how it uses the one below. | Layer | Package or Product | Documented in | |---|---|---| | Configuration | `agent.json` and the `telnyx-acp` CLI | [Agent Control Plane](/docs/agents) | | The managed harness | `@telnyx/acp` | [Inside the Managed Harness](/docs/agent-sdk/inside/generated-code) | | The harness | `@telnyx/agent-harness` | [The Agent Harness SDK](/docs/agent-sdk/harness-sdk) | | The runtime | `@telnyx/edge-runtime` | [The Agent Runtime SDK](/docs/agent-sdk/runtime-sdk) | | The platform | [Stateful Actors](/docs/edge-compute/stateful-actors) and [Functions](/docs/edge-compute/overview) | [Agent Runtime Platform](/docs/agents/runtime-platform/edge-compute-serverless) | The layers reach other Telnyx products as they run. - [Inference](/docs/inference/models) serves the model the harness calls. - [Agent Memory](/docs/agent-memory) gives the managed harness a person's summary before a turn, and keeps each exchange after it. - [STT](/docs/voice/stt/overview) and [TTS](/docs/voice/tts/overview) carry a call's speech for the runtime's voice layer. - The [Voice API](/docs/voice/programmable-voice/voice-api-fundamentals) answers each call with a media stream to the instance, and transfers and hangs up calls. - [Messaging](/docs/messaging/messages/send-message) and [Email](/docs/messaging/email/overview) bring texts and emails in through their webhooks, and carry the replies out. --- ### The Generated Code > Source: https://developers.telnyx.com/docs/agent-sdk/inside/generated-code.md ```bash telnyx-acp deploy ``` ```text {2,3,5,6,7,8,26,28} support-agent/ ├── agent.json ◀ ├── instructions.md ◀ └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ◀ ├── telnyx-env.d.ts ◀ └── package.json ◀ @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts ◀ │ ├── code-entry.ts │ └── vendor.ts ◀ └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` A configuration-based agent is a class the user never sees. It extends `Agent` from the [Agent Runtime SDK](/docs/agent-sdk/runtime-sdk) and drives the [Agent Harness SDK](/docs/agent-sdk/harness-sdk). This chapter opens it in the order the CLI builds it. This page is the code `deploy` generates. [Configuration](/docs/agent-sdk/inside/configuration/model) follows each field of `agent.json` into that code. [The Harness](/docs/agent-sdk/inside/harness) is where those fields are plugged in, once per activation. [Request Handling](/docs/agent-sdk/inside/request-handling/rpc-methods) follows each inbound request to its handler. [Turn Taking](/docs/agent-sdk/inside/turn-taking/admit) is the loop itself, from the admitted message to the delivered reply. Every piece named here can be overridden by the user, and [Extending the Managed Agent](/docs/agent-sdk/extending) describes how. `create` writes no code; [Project Layout](/docs/agents/project-layout) shows the files. The class comes into being at `deploy`, which generates `.telnyx/index.ts` from `agent.json`, with `instructions.md` inlined so that the deployed function reads no files. For `support-agent` the file is this, with the spec abbreviated: ```ts // Generated by `telnyx-acp deploy`. Do not edit: it is rewritten on every deploy. import { mountAgents } from "@telnyx/edge-runtime/mount"; import { defineManagedAgent } from "@telnyx/acp/managed"; import { channelRoutes } from "@telnyx/acp/channels"; // agent.json, with instructions.md inlined: the deployed function reads no files. const spec = { name: "support-agent", model: "zai-org/GLM-5.3-Flash", instructions: "…" } as const; export class SupportAgent extends defineManagedAgent(spec) {} export default { fetch: mountAgents((env) => ({ "support-agent": env.SUPPORT_AGENT }), { fallback: channelRoutes([], { agent: "support-agent", binding: "SUPPORT_AGENT" }), }), }; ``` Three lines carry the agent. - `export class SupportAgent extends defineManagedAgent(spec) {}` is the agent. `defineManagedAgent(spec)` is the managed harness bound to this spec, and `SupportAgent` is the actor type the platform runs, one instance per conversation. - [`mountAgents`](/docs/agent-sdk/internals/mount/mountAgents) is the function's `fetch`. It serves every conversation at `/agents/support-agent/`. - `channelRoutes` is the fallback for everything else the function receives, which is the webhooks. With `web` set, the options also carry `web`, and the fallback serves the chat page at `/web` and the embed script at `/web/embed.js` before the webhook routes. `mountAgents(map, { fallback })` is [`mountAgents()`](/docs/agent-sdk/internals/mount/mountAgents). - `map` is the whole routing table. Its one entry serves the actor namespace `env.SUPPORT_AGENT` under the mount name `support-agent`. - `fallback` receives every request whose path is outside `/agents`. Beside it, `deploy` writes `telnyx.toml`, the manifest that names the actor type and its binding, `telnyx-env.d.ts` with the types, and a `package.json`. It then links `@telnyx/acp` and `@telnyx/edge-runtime` into `.telnyx/node_modules`, in `synth/vendor.ts`, so that the bundle built on this machine resolves them. With a phone number, or a Call Control application among the channels, the base is `defineManagedVoiceAgent(spec)` instead; `export` writes the same class into `src/agent.ts` for the user to own, and counts a TeXML application as answering calls too. The module names on the pages that follow, `managed/agent.ts` and the rest, are files of the `@telnyx/acp` package. --- ### Model > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/model.md ```bash telnyx-acp set model zai-org/GLM-5.3-Flash ``` ```text {2,5,13,14,31} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts ◀ │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ◀ ├── phone.ts ├── project.ts └── io.ts ``` `model` is written by `create --model` and changed by `set model`. On a terminal, `set model` with no value opens the same searchable list as the wizard. At `deploy` it becomes `spec.model` in `.telnyx/index.ts`, and [`buildHarness()`](/docs/agent-sdk/inside/harness) in `managed/agent.ts` builds the language model from it: ```ts // managed/agent.ts, buildHarness() const model = this.host.model ?? chatLanguageModel((this.host.completions ?? defaultCompletions)(this.env, this.spec), this.spec.model); ``` `model` becomes the harness spec's [`model`](/docs/agent-sdk/harness-sdk/create-harness#spec-model). It is an AI SDK v6 language model, which `chatLanguageModel` implements over the chat completions. `chatLanguageModel` and `telnyxChatCompletions` are in `managed/model.ts`. The call goes to the Telnyx inference endpoint through the `TELNYX` binding of the instance's [`env`](/docs/agent-sdk/interface/env), as `ai.openai.chat.createCompletion`, and for a third-party model the key stored as a secret is added to the request as `api_key`. A host that supplies `model` replaces the language model outright; one that supplies `completions` keeps `spec.model` and changes the endpoint it is served from. --- ### Instructions > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/instructions.md ```md instructions.md You are the support agent for Acme. Answer in one or two sentences. ``` ```text {3,5,13,15} support-agent/ ├── agent.json ├── instructions.md ◀ └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts ◀ │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `instructions` names a file, and the file is edited directly; `set` does not touch it. At `deploy` its text is inlined into `spec.instructions` in `.telnyx/index.ts`, so the deployed function reads no files, and [`buildHarness()`](/docs/agent-sdk/inside/harness) in `managed/agent.ts` hands it to the harness, with the memory summary appended when memory is on: ```ts // managed/agent.ts, buildHarness() instructions: this.spec.memory ? withCard(this.spec.instructions, card) : this.spec.instructions, ``` `instructions` is the harness spec's [`instructions`](/docs/agent-sdk/harness-sdk/create-harness#spec-instructions), the model's system prompt on every step. The harness assembles nothing into it, so the summary is appended before the harness is built. `withCard` is in `managed/memory.ts`. It appends the line that tells the model it remembers people, then the profile's summary, bounded and fenced, or the first-conversation line when the profile has none: ```ts // managed/memory.ts export const MEMORY_CARD_MAX_CHARS = 2000; export function withCard(instructions, card) { const text = card?.trim(); const bounded = text && text.length > MEMORY_CARD_MAX_CHARS ? `${text.slice(0, MEMORY_CARD_MAX_CHARS).trimEnd()}\n[the notes continue; cut here]` : text; const known = bounded ? `${MEMORY_CARD_INTRO}\n\n${bounded}\n` : "This is your first conversation with this person; you know nothing about them yet."; return `${instructions.trimEnd()}\n\n${MEMORY_PREAMBLE}\n${known}`; } ``` `MEMORY_CARD_INTRO` says the notes are things the person said, kept for the model, and not instructions. The card summarizes what the person said, so a line planted in one conversation must not read as a rule in the next. The harness is built once per activation, so the summary it carries is the one read when the conversation started. --- ### Phone > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/phone.md ```bash telnyx-acp add phone +15550001234 ``` ```text {2,5,16,20,21,24} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts ◀ │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts ◀ │ ├── phone.ts ◀ │ ├── email.ts │ ├── web.ts │ └── wire.ts ◀ ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `add phone ` appends the number to `phone`. Before anything ships, `checkNumbers` in `channels/phone.ts` looks each number up in the account, and a missing or inactive number stops the `deploy`. At `deploy` three things follow from it. - `provisionPhones` in `channels/phone.ts` puts the number on a Call Control application for calls and a messaging profile for texts, created and named ` (telnyx-acp)` when the number is bare. `wireChannels` in `channels/wire.ts` points each artifact's webhook at the function, with the previous webhook remembered in `agent.json` so that `remove phone` and `delete` can restore it. They delete only the artifacts `deploy` created. - Two routes, one per artifact type with `*` for the id, go into the list passed to `channelRoutes` in `.telnyx/index.ts`, because the artifacts are created after the function is built. `channels/index.ts` serves them at `/webhooks/call_control_application/` and `/webhooks/messaging_profile/`. - The base class becomes `defineManagedVoiceAgent(spec)` from `managed/voice.ts`, because the agent now answers calls. It wraps the managed class in the `voice()` mixin from [`@telnyx/edge-runtime/voice`](/docs/agent-sdk/runtime-sdk). [The Messaging Webhook](/docs/agent-sdk/inside/request-handling/messaging-webhook) and [The Call Webhook](/docs/agent-sdk/inside/request-handling/call-webhook) follow a text and a call from there. --- ### Channels > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/channels.md ```bash telnyx-acp add channel messaging_profile: ``` ```text {2,5,20,24} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts ◀ │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ◀ ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `add channel :` appends an existing artifact to `channels`, by type and id, and never touches a number. At `deploy`, `wireChannels` in `channels/wire.ts` points the artifact's webhook at the function and remembers the previous value, and one route for it goes into the list passed to `channelRoutes` in `.telnyx/index.ts`. `channels/index.ts` serves every route at `/webhooks//` and verifies each webhook against the account's public key before reading it. A `messaging_profile` route runs `messagingWebhook`, a `call_control_application` route runs the call handler, and an `email_domain` route runs `emailWebhook`. A `texml_application` channel is declared and validated, but its handler is not implemented yet. A webhook to it answers 501. --- ### Voice > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/voice.md ```bash telnyx-acp set voice.greeting "Hello, how can I help?" telnyx-acp set voice.harness true ``` ```text {2,5,16,17,18} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts ◀ │ ├── direct-turn.ts ◀ │ └── filler.ts ◀ ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `voice` is written by `set voice.*`, or its `greeting` by the wizard when the project has a number. It becomes `spec.voice` in `.telnyx/index.ts`, and four functions in `managed/voice.ts` read it: ```ts // managed/voice.ts export function answerOptions(spec) { const v = spec.voice ?? {}; return { eager: v.eager ?? true, ...(v.bargeIn !== undefined ? { bargeIn: v.bargeIn } : {}), ...(v.keypressInterrupts !== undefined ? { keypressInterrupts: v.keypressInterrupts } : {}) }; } export function speechOptionsFor(spec) { const v = spec.voice ?? {}; return { recognizer: { ...(v.stt ?? {}) }, synthesizer: { voice: v.tts?.voice ?? DEFAULT_TTS_VOICE, ...(v.tts?.voiceSettings ? { voiceSettings: v.tts.voiceSettings } : {}) } }; } export function defaultGreeting(spec) { return spec.voice?.greeting?.trim() || `Hi, this is ${spec.name.replace(/[-_]+/g, " ")}. How can I help?`; } export function harnessOnCalls(spec) { return spec.voice?.harness === true; } ``` - `answerOptions` is what the voice class passes to the `voice()` mixin's `answer` when the media socket opens, as [The Call Webhook](/docs/agent-sdk/inside/request-handling/call-webhook) shows. - `speechOptionsFor` feeds `speechProvidersFor`, which builds the STT and TTS providers. - `defaultGreeting` is returned by the voice class's `greeting`, and spoken when the call is answered. - `harnessOnCalls` chooses the turn engine, the direct engine in `managed/direct-turn.ts` by default and the harness when `voice.harness` is true. `answerOptions(spec)` sets the mixin's call options. - `eager` is on unless `voice.eager` is false. A turn then starts on STT's first guess that the caller has finished, and its audio is held until the guess is confirmed. - `bargeIn` and `keypressInterrupts` are passed only when `voice` sets them, and the mixin's own defaults apply otherwise. `speechProvidersFor` hands the speech options to the runtime SDK: ```ts // managed/voice.ts export function speechProvidersFor(spec, make = telnyxSpeechProviders) { return make(speechOptionsFor(spec)); } ``` `telnyxSpeechProviders(options)` is the Telnyx STT and TTS pair from [`@telnyx/edge-runtime/voice`](/docs/agent-sdk/runtime-sdk). Its `recognizer` option tunes STT and its `synthesizer` option tunes TTS. Both reach Telnyx over the runtime's own connection, with no credential in the class. A fifth, `fillerOptions` in `managed/filler.ts`, reads `voice.filler`: ```ts // managed/filler.ts export function fillerOptions(spec) { const f = spec.voice?.filler; if (f === false) return undefined; return { afterMs: f?.afterMs ?? DEFAULT_FILLER_AFTER_MS, phrases: f?.phrases?.length ? f.phrases : DEFAULT_FILLER_PHRASES, maxPerCall: f?.maxPerCall ?? 0 }; } ``` `fillerOptions` is what the voice class's `reply` uses to say one short phrase when the model is slow to start. `DEFAULT_FILLER_AFTER_MS` is 700, and the default phrases are "One moment.", "Let me check that for you." and "Sure, just a second.". [The Voice Loop](/docs/agent-sdk/inside/turn-taking/voice-loop) is where the phrase is spoken. [Voice](/docs/agents/voice) is the user-facing side of the same fields. --- ### Memory > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/memory.md ```bash telnyx-acp set memory '{ "type": "agent_memory", "namespace": "default", "profile": "{{conversation}}" }' ``` ```text {2,5,13,15} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts ◀ │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` The `memory` block is written by `set memory`, or by the wizard. It becomes `spec.memory` in `.telnyx/index.ts`, and each conversation's memory is built on demand by `memory()` in `managed/agent.ts`: ```ts // managed/agent.ts async memory() { const conversation = this.memoryConversation ?? (await this.getState()).from ?? this.conversationName(); if (conversation === undefined) return undefined; if (conversation !== this.memoryKey) { this.memoryKey = conversation; this.memoryInstance = createAgentMemory(this.spec.memory, this.env.TELNYX, conversation); } return this.memoryInstance; } ``` `this.getState()` is [`getState()`](/docs/agent-sdk/interface/getState). Its `from` is the sender that `admit` wrote. On a fresh instance it returns [`initialState()`](/docs/agent-sdk/interface/initialState), which the class defines as `{}`. `this.env.TELNYX` is the Telnyx binding of the instance's [`env`](/docs/agent-sdk/interface/env). Both calls on Agent Memory go through it, and without it there is no memory. The conversation key is the caller's number on a call, set by the voice class, or the sender of the last text or email, held in state. A conversation with neither, such as one reached by `invoke` or `chat`, is keyed on its own name, which `conversationName()` decodes from the instance's id: ```ts // managed/agent.ts conversationName() { try { return decodeAgentName(this.ctx.id); } catch { return undefined; } } ``` `decodeAgentName(this.ctx.id)` is [`decodeAgentName()`](/docs/agent-sdk/internals/mount/decodeAgentName). - `this.ctx.id` is the instance's actor id, from [`ctx`](/docs/agent-sdk/interface/ctx), which the mount encoded from the conversation's name. - It returns that name, such as `alice` for `invoke --conversation alice`. - It throws for an id the mount did not make. The key is then undefined, and the conversation has no memory. `createAgentMemory` in `managed/memory.ts` resolves `{{conversation}}` in the profile template to that key and makes two calls on Agent Memory. - The summary is read at the start, bounded by `CARD_TIMEOUT_MS` of one second. - The conversation is pushed at the end. [Memory](/docs/agents/memory) is the user-facing page. --- ### Tools, Approvals and Limits > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/tools.md ```bash telnyx-acp add tool web_search telnyx-acp add tool mcp --url https://mcp.deepwiki.com/mcp telnyx-acp set approvals. ask telnyx-acp set limits.steps 12 ``` ```text {2,5,13} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── tools.ts ◀ │ ├── mcp.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `add tool` writes `tools`, `set approvals.` writes `approvals`, and `set limits.steps` writes `limits`. All three reach [`buildHarness()`](/docs/agent-sdk/inside/harness) in `managed/agent.ts`, which `harness()` calls with the spec's approvals and `callHarness()` with every `ask` turned to `deny`: ```ts // managed/agent.ts, buildHarness(card, approvals) const { tools, activeTools, authorization } = applyApprovals({ ...specTools(this.spec, this.toolEnv()), ...(this.host.tools ?? {}) }, approvals, this.host.approvalTtlMs); // … limits: { steps: this.spec.limits?.steps ?? DEFAULT_STEPS }, ``` `specTools`, in `managed/tools.ts`, builds a tool set in the `ai` package's shape from the `tools` entries of `agent.json`: for a `web_search` entry, `web_search`, plus `fetch_page` unless `contents` is false and `research` when `research` is true, over the function's `TELNYX` binding; for an `mcp` entry, one tool per listed server tool, named `__`, its input schema the server's JSON Schema, each call made by the Streamable HTTP client in `managed/mcp.ts` with the secret read through `toolEnv().secret` at every request. A host's own tools are merged on top, a host tool of the same name winning. Every built tool catches its own failure and answers the model with `{ error }`, and writes one `toolCall` log line. `applyApprovals`, in `managed/agent.ts`, takes that tool set and the approval policy and returns the tools the harness may call, the ones marked `ask` that pause for a decision, and the authorization that decides them. The policy is one word per tool. | `approvals.` | Effect | |---|---| | `allow`, the default | The tool is offered as it is. | | `ask` | The tool is marked as needing approval, and its action is `agent.tools.`, with any character of the name outside letters and digits escaped. On a call it is `deny`: a call cannot wait for an approval. | | `deny` | The tool is left out of the set, and `activeTools` lists the rest. | `applyApprovals` and the step limit fill four fields of the harness spec. - `tools` is the spec's [`tools`](/docs/agent-sdk/harness-sdk/create-harness#spec-tools). An `ask` tool is passed with `needsApproval: true`, the one value the harness accepts. - `activeTools` is the spec's [`activeTools`](/docs/agent-sdk/harness-sdk/create-harness#spec-activetools), passed only when a tool is denied. - `authorization` is the spec's [`authorization`](/docs/agent-sdk/harness-sdk/create-harness#spec-authorization), passed only when a tool is marked `ask`. It maps every tool in the set to an action, as the harness requires, and carries the host's `approvalTtlMs`. - `limits.steps` is the spec's [`limits`](/docs/agent-sdk/harness-sdk/create-harness#spec-limits). A run whose last allowed step still calls a tool fails with `HARNESS_STEP_LIMIT`. `DEFAULT_STEPS` is 8, and an approval lives fifteen minutes by default from its request, within the harness's bounds of five minutes and twenty-four hours. The managed classes attach neither the [scheduling tools](/docs/agent-sdk/harness-sdk/plug-ins/scheduling) nor the [workspace tools](/docs/agent-sdk/harness-sdk/plug-ins/workspace) of the harness package. An `agent_gateway` entry is validated and deployed, but `specTools` builds nothing for it: the gateway client has not landed, so its tools are not called. --- ### Secrets > Source: https://developers.telnyx.com/docs/agent-sdk/inside/configuration/secrets.md ```bash telnyx-acp add secret OPENAI_API_KEY ``` ```text {2,6,13,14,26,31} support-agent/ ├── agent.json ◀ ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ├── telnyx.toml ◀ ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts ◀ │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts ◀ │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ◀ ├── phone.ts ├── project.ts └── io.ts ``` `add secret NAME` prompts for the value, stores it on the platform, and appends the name to `secrets`. At `deploy`, `manifest()` in `synth/index.ts` writes one `[[secrets]]` entry per name into `.telnyx/telnyx.toml`, after the function's identity, the actor and the Telnyx binding: ```toml # Generated by `telnyx-acp deploy` from agent.json. Do not edit; never commit. name = "support-agent" main = "index.ts" compatibility_date = "2026-10-01" [edge_compute] func_id = "…" func_name = "support-agent" [[actors]] binding = "SUPPORT_AGENT" type = "SupportAgent" [telnyx] binding = "TELNYX" [[secrets]] binding = "OPENAI_API_KEY" name = "OPENAI_API_KEY" ``` The class reads each secret through `env.SECRETS.get(name)`, on the instance's [`env`](/docs/agent-sdk/interface/env). A third-party model's key is read by `modelKey` in `managed/agent.ts` under the name that `spec/model.ts` maps the provider to, and `managed/model.ts` sends it as `api_key` on each request. | Provider | Secret | |---|---| | `openai/*` | `OPENAI_API_KEY` | | `anthropic/*` | `ANTHROPIC_API_KEY` | | `google/*` | `GOOGLE_API_KEY` | | `groq/*` | `GROQ_API_KEY` | `modelKey` reads the secret: ```ts // managed/agent.ts async function modelKey(env, model) { const secret = modelKeySecret(model); if (!secret || !env.SECRETS) return undefined; try { return (await env.SECRETS.get(secret)) || undefined; } catch { return undefined; } } ``` `env.SECRETS` is the secrets binding of the instance's [`env`](/docs/agent-sdk/interface/env), present when `telnyx.toml` declares a secret. - `secret` is the name that `modelKeySecret` maps the provider to, as in the table. - A missing binding, a missing secret or a failed read leaves the key out. The inference API then answers with what it needs, and that answer is written to state as `lastError`. --- ### The Harness > Source: https://developers.telnyx.com/docs/agent-sdk/inside/harness.md ```text {13,14,15} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts ◀ │ ├── memory.ts ◀ │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` The harness is the apparatus the configuration is plugged into, the model, the tools, the instructions and the step limit, and every run of the turn taking is pulled through it. It is the harness SDK's [`createHarness()`](/docs/agent-sdk/harness-sdk/create-harness), built once per activation by `harness(card)` in `managed/agent.ts`: ```ts // managed/agent.ts harness(card) { return (this.harnessInstance ??= this.buildHarness(card, this.spec.approvals ?? {})); } buildHarness(card, approvals) { const { tools, activeTools, authorization } = applyApprovals({ ...specTools(this.spec, this.toolEnv()), ...(this.host.tools ?? {}) }, approvals, this.host.approvalTtlMs); const model = this.host.model ?? chatLanguageModel((this.host.completions ?? defaultCompletions)(this.env, this.spec), this.spec.model); return createHarness({ ports: this.buildPorts(), model: observeModelErrors(model, (message) => { this.modelError = message; }), tools, ...(activeTools ? { activeTools } : {}), ...(authorization ? { authorization } : {}), instructions: this.spec.memory ? withCard(this.spec.instructions, card) : this.spec.instructions, limits: { steps: this.spec.limits?.steps ?? DEFAULT_STEPS }, }); } ``` `callHarness(card)` builds a second harness for calls when a tool is marked `ask`: a turn on a call is not a durable run, and nobody can approve while the caller waits, so every `ask` becomes `deny` for that harness and the agent says so once in the logs, `{"voiceTools":"left out on calls","tools":[…]}`. Without any `ask`, calls use the very same instance. The class fills seven fields of the spec. - [`ports`](/docs/agent-sdk/harness-sdk/create-harness#spec-ports) is `buildPorts()`, the instance's own runtime ports. - [`model`](/docs/agent-sdk/harness-sdk/create-harness#spec-model) is the host's `model`, or else `chatLanguageModel` for `spec.model`. `observeModelErrors` wraps it so that a failed run can record the model's own error message. - [`tools`](/docs/agent-sdk/harness-sdk/create-harness#spec-tools) is the tool set as `applyApprovals` leaves it: the tools `specTools` builds from `agent.json` ([Tools, Approvals and Limits](/docs/agent-sdk/inside/configuration/tools)), with the host's merged on top. - [`activeTools`](/docs/agent-sdk/harness-sdk/create-harness#spec-activetools) is passed only when a tool is denied. - [`authorization`](/docs/agent-sdk/harness-sdk/create-harness#spec-authorization) is passed only when a tool is marked `ask`. - [`instructions`](/docs/agent-sdk/harness-sdk/create-harness#spec-instructions) is `spec.instructions`, with the memory summary appended when memory is on. - [`limits`](/docs/agent-sdk/harness-sdk/create-harness#spec-limits) is `{ steps }`, from `spec.limits.steps` or `DEFAULT_STEPS`. The host, the second argument of `defineManagedAgent(spec, host)`, supplies the tools and can replace the model. [Extending the Managed Agent](/docs/agent-sdk/extending#the-host) lists its fields. The ports are built over the instance itself: ```ts // managed/agent.ts constructor(ctx, env, spec, host = {}) { super(ctx, env); this.spec = spec; this.host = host; if (host.authorization) setAgentHarnessAuthorizationProvider(this, host.authorization); } // … buildPorts() { return createRuntimeAgentHarnessPorts(this, { ...(this.host.environmentKeys ? { environmentKeys: this.host.environmentKeys } : {}), }); } ``` `super(ctx, env)` is the runtime SDK's [`constructor()`](/docs/agent-sdk/interface/constructor), and `createRuntimeAgentHarnessPorts(this, { environmentKeys })` is [`createRuntimeAgentHarnessPorts()`](/docs/agent-sdk/harness-sdk/adapters/runtime). - `this` is the instance. The harness reaches its storage and scheduler only through the [ports](/docs/agent-sdk/harness-sdk/ports). - [`environmentKeys`](/docs/agent-sdk/harness-sdk/adapters/runtime#runtimeagentharnessportsoptions) is the host's. It names the bindings that cross into the ports, and none cross without it. - `setAgentHarnessAuthorizationProvider`, from `@telnyx/edge-runtime/internal`, registers the host's `authorization` as the instance's [authorization port](/docs/agent-sdk/harness-sdk/ports/authorization#on-the-agent-runtime). Approvals fail closed without it. The managed classes attach none of the harness SDK's plug-ins. A class of the user's own can add each of them. - [`createHarnessWithScheduling()`](/docs/agent-sdk/harness-sdk/plug-ins/scheduling) adds tools with which the model schedules its own follow-ups. - [`createVirtualWorkspace()`](/docs/agent-sdk/harness-sdk/plug-ins/workspace) adds a per-instance text store with skills, which the model reads and writes through tools. - [`HarnessMiddleware`](/docs/agent-sdk/harness-sdk/plug-ins/middleware) wraps a turn, a model step or a tool call. --- ### The RPC Methods > Source: https://developers.telnyx.com/docs/agent-sdk/inside/request-handling/rpc-methods.md ```bash telnyx-acp invoke support-agent --conversation alice "hi" telnyx-acp rpc support-agent --conversation alice approve ``` ```text {5,13} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` A POST to `/agents///rpc/` calls one method on the conversation's instance. [`mountAgents`](/docs/agent-sdk/internals/mount/mountAgents) resolves the address to the instance and hands the POST to the class's [`fetch()`](/docs/agent-sdk/interface/fetch), and only a method marked [`@rpc`](/docs/agent-sdk/interface/rpc) answers. Who may call is decided by [`authorize()`](/docs/agent-sdk/interface/authorize), which [The Streams](/docs/agent-sdk/inside/request-handling/streams) shows with `fetch`. The class marks five methods. ## receive() `invoke`, `chat` and `rpc … receive` post `["text"]` to `…/rpc/receive`: ```ts // managed/agent.ts async receive(text, from, key) { return this.admit(text, from, key); } ``` The reply is not returned from this call. It arrives through the task the harness queues and is read back on the state stream as `lastReply`, which is what `invoke` waits for. It is never sent out on a channel. `key` makes a redelivered message a no-op, answered with `duplicate: true`. [Admit](/docs/agent-sdk/inside/turn-taking/admit) is the next step. `receive` carries [`@rpc`](/docs/agent-sdk/interface/rpc), as `@rpc({ description: "Deliver one inbound message; the reply is produced off the request path" })`. - Only a method that carries it dispatches over the mount. Every other method of the class is private there. - `description` is what [`rpcSurface()`](/docs/agent-sdk/interface/rpcSurface) reports for the method. ## Approvals and Runs `approve`, `deny`, `inspectApproval`, `pendingApproval` and `run` are reached the same way, and through `telnyx-acp rpc`: ```ts // managed/agent.ts async approve(approvalId) { return (await this.ready()).approvals.grant(approvalId); } async deny(approvalId) { return (await this.ready()).approvals.deny(approvalId); } async inspectApproval(approvalId){ return (await this.ready()).approvals.inspect(approvalId); } async pendingApproval(runId) { const hit = await this.pendingApprovalFor(runId); return hit ? { id: hit.id, runId, toolName: hit.toolName } : undefined; } async run(runId) { return (await this.ready()).get(runId); } ``` Each reads or writes the harness's own ledger, which holds the pending approvals and the status of every run. A run paused on an `ask` continues on its own task once `approve` grants its approval. `pendingApproval` names the approval a paused run waits on, read from the ledger on that later call; `telnyx-acp invoke` asks for it when the state stream has not named it. `approvals.grant()`, `approvals.deny()` and `approvals.inspect()` are the harness's [`approvals`](/docs/agent-sdk/harness-sdk/harness/approvals) ledger, and `get(runId)` is the harness's [`get()`](/docs/agent-sdk/harness-sdk/harness/get). - `approvalId` names an approval, and each of the three returns its [`HarnessApproval`](/docs/agent-sdk/harness-sdk/harness/approvals#harnessapproval). - `deny()` also continues the run. The call is not executed, and the model is told it was denied. - Each of the three is checked against the authorization port for its [required action](/docs/agent-sdk/harness-sdk/harness/approvals#required-actions). The constructor registers that port from the host's `authorization`, as [The Harness](/docs/agent-sdk/inside/harness) shows. - `runId` names a run, and `get()` returns its [`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun), or `undefined` for an unknown id. - Each method calls `ready()` first, so the runs a restart interrupted are recovered before anything is read or decided. --- ### The Streams > Source: https://developers.telnyx.com/docs/agent-sdk/inside/request-handling/streams.md ```bash telnyx-acp invoke support-agent --conversation alice --stream "hi" ``` ```text {5,13} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` A WebSocket upgrade, or `GET …?subscribe=state`, on a conversation's address opens the stream of its state and messages. No turn runs. [`mountAgents`](/docs/agent-sdk/internals/mount/mountAgents) hands the upgrade to the runtime's default [`webSocket()`](/docs/agent-sdk/interface/webSocket), and the GET, like an RPC's POST, to the class's `fetch`: ```ts // managed/agent.ts fetch(req) { return (this.door ??= new AgentHttpServer(this.connectionEngine)).fetch(req); } ``` `fetch(req)` overrides the runtime SDK's [`fetch()`](/docs/agent-sdk/interface/fetch) with an [`AgentHttpServer`](/docs/agent-sdk/internals/the-http-server) over [`connectionEngine`](/docs/agent-sdk/interface/connectionEngine). - The server answers a GET with Server-Sent Events, and a POST to `…/rpc/` with one RPC call. - `connectionEngine` is the engine the default `webSocket()` runs every socket through, so both transports serve the same streams under the same `authorize`. - The server is built on the first request and kept for the activation. `authorize` decides who may read the streams and who may call the [`@rpc`](/docs/agent-sdk/interface/rpc) methods: ```ts // managed/agent.ts authorize(token, req) { return this.host.authorize ? this.host.authorize(token, req) : ["read", "rpc"]; } ``` `authorize(token, req)` overrides the runtime SDK's [`authorize()`](/docs/agent-sdk/interface/authorize). - `token` is the credential the caller presented, or `undefined` without one. - `req` is the request, with any identity headers a front door stamped on it. - The returned claims are the caller's grants, and a throw rejects the caller. The runtime acts on `"rpc"` alone, which admits the `@rpc` methods. - The runtime's own default returns `["read"]`, which admits the streams and no RPC. The voice class overrides `webSocket()` to answer calls: an upgrade whose address carries `?media=call` is a call's media, as [The Call Webhook](/docs/agent-sdk/inside/request-handling/call-webhook) shows, and any other upgrade is the agent socket protocol, as here. Without a host `authorize`, every caller is granted read and RPC — including the approvals methods: `pendingApproval` and `inspectApproval` expose the pending approval (tool name, required action, arguments), and `approve`/`deny` decide it. --- ### The Messaging Webhook > Source: https://developers.telnyx.com/docs/agent-sdk/inside/request-handling/messaging-webhook.md ```bash telnyx-acp text support-agent "hi" ``` ```text {5,13,20} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts ◀ │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `POST /webhooks/messaging_profile/`. `channelRoutes` verifies the signature, then `messagingWebhook` in `channels/index.ts` reads the event: ```ts // channels/index.ts export async function messagingWebhook(event, env, route, options) { const data = event?.data; if (!data || data.event_type !== "message.received") return new Response("ok"); const p = data.payload ?? {}; const from = p["from"]?.phone_number, to = (p["to"] ?? [])[0]?.phone_number, text = p["text"], id = p["id"]; // …type checks; media-only messages and other profiles' messages are acknowledged and ignored const via = { kind: "messaging", profileId: route.id, from, to }; const result = await stubFor(env, options.binding, from).receiveVia(text, from, id, via); return Response.json({ ok: true, conversation: from, ...result }); } ``` The sender's number is the conversation, and `stubFor` addresses its instance exactly as the mount does: ```ts // channels/index.ts function stubFor(env, binding, conversation) { const ns = env[binding]; if (!ns || typeof ns.idFromName !== "function") throw new Error(`binding ${binding} is not an actor namespace`); return ns.idFromName(encodeAgentName(conversation)); } ``` `encodeAgentName(conversation)` is [`encodeAgentName()`](/docs/agent-sdk/internals/mount/encodeAgentName), the encoding the mount applies to the name in every address. - `conversation` is the sender's number, so the text reaches the same instance as `/agents/support-agent/`. - `env[binding]` is the actor namespace that `telnyx.toml` binds, and `idFromName` returns the stub of the instance with that id. The stub calls any public method of the class in-process. `receiveVia` in `managed/agent.ts` is the second ingress path, and deliberately not [`@rpc`](/docs/agent-sdk/interface/rpc), so only the function's own handlers, which verified the signature, can name where a reply goes: ```ts // managed/agent.ts async receiveVia(text: string, from: string, key: string, via: ReplyVia): Promise<{ runId: string; duplicate: boolean }> { assertReplyVia(via); // Written before the run exists, under the message's key: the run's task may // run the moment it is queued, and it finds its channel by the key it carries. await this.setState({ replyTo: { [key]: via } }); return this.admit(text, from, key); } ``` `this.setState()` is [`setState()`](/docs/agent-sdk/interface/setState). - The entry is keyed by the message's key, not the run's id, and written before `admit` queues the run, since the run's task may start the moment it is queued; [Delivery](/docs/agent-sdk/inside/turn-taking/delivery) reads it as `state.replyTo?.[run.key]`. - `setState()` merges the patch, so the new `replyTo` entry joins those of other messages. - A redelivered message carries the same key, so it overwrites its own entry with the same target and `admit` answers `duplicate: true`. - `noteRun` deletes the entry with `null` once the run ends. The message id is the key, so a redelivered webhook runs nothing. `via` is kept in state under the message key, before the run exists, and [Delivery](/docs/agent-sdk/inside/turn-taking/delivery) reads it when the run completes. --- ### The Call Webhook > Source: https://developers.telnyx.com/docs/agent-sdk/inside/request-handling/call-webhook.md ```text Dial +15550001234 from any phone. ``` ```text {5,16,20} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ◀ ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts ◀ │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts ◀ │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` `POST /webhooks/call_control_application/`. `channelRoutes` verifies the signature, then the call handler in `channels/index.ts` acts on `call.initiated` for an incoming leg. 1. It wakes the call's instance, `warmCall(from)` on the conversation named by the call's id, so that the instance is placed and running and the caller's memory read has begun. The caller hears ringing meanwhile, typically one to three seconds. 2. It answers the inbound leg with the media stream requested in the same command, so the media starts the moment the leg is up. 3. The media server opens a WebSocket to `/agents//?media=call`. [`mountAgents`](/docs/agent-sdk/internals/mount/mountAgents) hands it, query and all, to the instance's [`webSocket()`](/docs/agent-sdk/interface/webSocket), where the voice class answers the call. The `media=call` pair is what tells it a call's media from any other socket to the conversation: an upgrade without it is a client on the agent socket protocol, and goes to the text agent's `webSocket()` instead. The first two steps are the handler's own: ```ts // channels/index.ts, voiceWebhook() await warm(callControlId, typeof payload["from"] === "string" ? payload["from"] : undefined); await calls.command(callControlId, "answer", { client_state: INBOUND_LEG_STATE, stream_url: mediaStreamUrl(`wss://${host}`, agent, callControlId), // …/agents//?media=call stream_track: "inbound_track", // …a bidirectional PCMU stream at 8000 Hz, back to the same leg }); ``` `calls` is `createCallControlClient()` from [`@telnyx/edge-runtime/voice`](/docs/agent-sdk/runtime-sdk). Its `command` goes out over the runtime's own connection, so the function holds no key. `warm` calls `warmCall` on the instance's stub, as [The Messaging Webhook](/docs/agent-sdk/inside/request-handling/messaging-webhook) shows for a text. The instance takes the call in `managed/voice.ts`: ```ts // managed/voice.ts webSocket(ws, req) { // Only a call's media stream is answered with the voice layer: its address // carries `?media=call`. Any other upgrade is a client on the agent socket // protocol, which the text agent's `webSocket` serves. if (!isMediaUpgrade(req)) return super.webSocket(ws, req); this.answer(ws, answerOptions(spec)); const engine = this.turnEngine(); void (engine instanceof Promise ? engine : engine.warm()).catch(() => undefined); } warmCall(from) { this.nameCaller(from); const engine = this.turnEngine(); void (engine instanceof Promise ? engine : engine.warm()).catch(() => undefined); } ``` `webSocket(ws, req)` overrides the runtime SDK's [`webSocket()`](/docs/agent-sdk/interface/webSocket). - It reads the mark off the upgrade's address: `?media=call` is the media server's socket, answered with the voice layer and never handed to `super.webSocket()`; anything else is a client on the agent socket protocol and goes to `super.webSocket(ws, req)`, as on a text agent. - `this.answer(ws, answerOptions(spec))` is the `voice()` mixin's `answer`. It takes the media socket and the options from `voice`, and runs the call from then on. - Both methods start the turn engine's first reading, the harness's `ready()` or the direct engine's `warm()`, so that the first turn does not wait for it. - `warmCall` carries no [`@rpc`](/docs/agent-sdk/interface/rpc), so over the mount it is private, and only the handler reaches it. `streaming.started`, `streaming.failed` and `call.hangup` on the answered leg are logged as one line each; a call that connects but stays silent explains itself in `streaming.failed`. [The Voice Loop](/docs/agent-sdk/inside/turn-taking/voice-loop) is the turn taking that follows. --- ### Admit > Source: https://developers.telnyx.com/docs/agent-sdk/inside/turn-taking/admit.md ```text {13} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` Every ingress path ends at `admit` in `managed/agent.ts`, and from this point on the loop is the same whether the text came by `invoke`, by RPC, from the messaging webhook or from another channel. A call is the one exception, and [The Voice Loop](/docs/agent-sdk/inside/turn-taking/voice-loop) describes it. ```ts // managed/agent.ts async admit(text, from, key) { if (typeof text !== "string" || text.trim() === "") throw new TypeError("receive(text) needs a non-empty string"); if (from !== undefined) await this.setState({ from }); // before the harness is built: its instructions carry this caller's memory const harness = await this.ready(); const accepted = await harness.accept(text, { key: key ?? randomUUID() }); return { runId: accepted.runId, duplicate: accepted.duplicate }; } ``` Three things happen. - The sender is written to state first, so that the memory profile is known before the harness exists. - `ready()` returns the harness, building it on the first call of an activation and recovering any run a crash interrupted. - [`accept()`](/docs/agent-sdk/harness-sdk/harness/accept) admits one run under the key and queues it as a task on the instance. `this.setState({ from })` is [`setState()`](/docs/agent-sdk/interface/setState). It merges `from` into the state and leaves every other key as it was. `harness.accept(text, { key })` is [`accept()`](/docs/agent-sdk/harness-sdk/harness/accept). - `text` is the input the run executes. - `key` is the idempotency key. It is the caller's `key`, or a fresh UUID when none was given. - A key seen before returns the first run with `duplicate: true` and admits nothing. - `runId` and `duplicate` are what `admit` returns to the caller. `ready()` builds the harness and recovers it: ```ts // managed/agent.ts async ready(opts = {}) { const built = opts.calls ? this.callHarnessInstance : this.harnessInstance; let card; if (!built && this.spec.memory) { const memory = await this.memory(); card = await memory?.card(); } const harness = opts.calls ? this.callHarness(card) : this.harness(card); const shared = opts.calls && harness === this.harnessInstance; const run = () => harness.recover().then(() => undefined, (err) => { if (opts.calls && !shared) this.callRecovery = undefined; else this.recovery = undefined; throw err; }); if (opts.calls && !shared) await (this.callRecovery ??= run()); else await (this.recovery ??= run()); return harness; } ``` A call asks for `ready({ calls: true })`, which [The Voice Loop](/docs/agent-sdk/inside/turn-taking/voice-loop) covers: the harness for calls leaves out every tool marked `ask`, and is the same instance when there is none. `harness.recover()` is [`recover()`](/docs/agent-sdk/harness-sdk/harness/recover). - It queues the task of every run still to be executed, including the runs a restart interrupted. - Every entrypoint that touches the harness goes through `ready()`, so recovery runs once per activation, before any new work. - A recovery that throws is tried again by the next call. `admit` returns the run id at once, well inside the 30-second budget of the inbound call. [The Harness](/docs/agent-sdk/inside/harness) is what `ready()` built. --- ### The Run > Source: https://developers.telnyx.com/docs/agent-sdk/inside/turn-taking/run.md ```text {13} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` The run executes as a task on the instance. The harness's tasks arrive at `onTask` in `managed/agent.ts`, which hands them to the harness: ```ts // managed/agent.ts async onTask(name, payload, info) { if (name === DELIVERY_TASK) { await this.retryDelivery(payload); return; } // a reply's next try; see Delivery if (!name.startsWith(HARNESS_TASK_PREFIX)) { await super.onTask(name, payload, info); return; } const harness = await this.ready(); const before = (await this.messages.last())?.seq ?? 0; // runs are dispatched one at a time, so what the log gains is this run's this.modelError = undefined; const run = await harness.dispatch({ name, payload }); await this.noteRun(run, before); } ``` `onTask(name, payload, info)` overrides the runtime SDK's [`onTask()`](/docs/agent-sdk/interface/onTask), the fallback for a task whose name is not a method of the class. - The harness's task names start with `HARNESS_TASK_PREFIX`, `__telnyx_agent_harness_`, and name no method of the class, so the tasks arrive here. - `DELIVERY_TASK`, `__telnyx_acp_deliver`, is the next try at a reply the channel refused; [Delivery](/docs/agent-sdk/inside/turn-taking/delivery) has the window. - Any other task goes to `super.onTask`, the runtime's default, which treats it as delivered. `this.messages.last()` is [`last()`](/docs/agent-sdk/interface/messages#last) on the message log. Runs are dispatched one at a time, so every message past the `seq` it returns is this run's. `harness.dispatch({ name, payload })` is [`dispatch()`](/docs/agent-sdk/harness-sdk/harness/dispatch). - `name` and `payload` are the task as the harness queued it. - It executes the run's turn and returns the run's [`HarnessRun`](/docs/agent-sdk/harness-sdk/harness/get#harnessrun) as the turn left it. Inside `dispatch`, three things happen. - The model is called with the instructions and the conversation's message log. - Tools run, subject to their approvals. - Each assistant message is appended to the log as it lands. When `dispatch` returns, `noteRun` writes the outcome to state, through the runtime SDK: ```ts // managed/agent.ts async noteRun(run, before) { if (!run) return; const state = await this.getState(); const last = await this.messages.last(); const reply = last && last.seq > before && last.role === "assistant" && last.content.trim() !== "" ? last.content : undefined; // … const at = this.now(); const patch = {}; // …the outcome's fields, as in the table below if (Object.keys(patch).length) await this.setState(patch); // …delivery, then the memory push } ``` - [`getState()`](/docs/agent-sdk/interface/getState) returns the runs already noted, so a redelivered task does not note a run twice. - [`last()`](/docs/agent-sdk/interface/messages#last) returns the newest message. It is the reply only when its `seq` is past `before`, its role is `assistant` and it has text. - [`now()`](/docs/agent-sdk/interface/now) is the time a completed or failed outcome records as `at`. - [`setState()`](/docs/agent-sdk/interface/setState) merges the patch. A `null` in it deletes a key, as it deletes `awaitingApprovalRunId` once that run ends. The outcome decides the keys written. | Outcome | State | |---|---| | Completed with a reply | `lastReply`, `lastRunId`, and an entry in `pendingDeliveries` under the run id when the message came in through a channel | | Completed with nothing to say | `lastRunId`, `failedRunId`, `lastError: "EMPTY_REPLY"` | | Failed | `lastRunId`, `failedRunId`, `lastError` with the model's own message when it threw | | Paused on an `ask` | `awaitingApprovalRunId` | The state stream carries each of these, which is how `invoke` ends with a reply, or with a line that says why there is none. With memory on, a completed run's exchange is pushed to Agent Memory under the run's id. [Delivery](/docs/agent-sdk/inside/turn-taking/delivery) is the last step. --- ### Delivery > Source: https://developers.telnyx.com/docs/agent-sdk/inside/turn-taking/delivery.md ```text {13} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts ◀ │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts │ ├── direct-turn.ts │ └── filler.ts ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` A reply to a message that came in through a channel goes back the same way. `noteRun` finds the `via` that `receiveVia` stored under the message's key before the run was admitted, records the reply in `pendingDeliveries` under the run id, and hands it to `sendPending`, the first of its tries: ```ts // managed/agent.ts, noteRun() const via = state.replyTo?.[run.key] ?? state.replyTo?.[run.id]; // …the outcome is written to state, pendingDeliveries[run.id] with it const pending = patch["pendingDeliveries"]?.[run.id] ?? pendingFor(state, run.id); const error = errorFor(state, run.id); // a retry already on the clock, or final const waiting = error && !error.final && error.nextAt !== undefined && error.nextAt > this.now(); if (pending && !delivered(state, run.id) && run.status === "completed" && !waiting) await this.sendPending(pending, (error?.attempts ?? 0) + 1); ``` `state` is what [`getState()`](/docs/agent-sdk/interface/getState) returned at the start of `noteRun`, and the writes go through [`setState()`](/docs/agent-sdk/interface/setState). - `replyTo` holds the `via` that `receiveVia` stored, under the message's idempotency key before the run was queued, so a run that completes at once still finds it. - `pendingDeliveries[run.id]` is written with the outcome before `deliver` runs, so a redelivered task still finds it; one entry per run, so a second run's reply never displaces a first run's that is still waiting on a retry. - `runStarts[run.id]` is the message-log position written before the run's first dispatch; a redelivered task reads the same boundary, so its own reply is never mistaken for one already there. - `deliveredRuns` lists the runs sent, and a `null` under `pendingDeliveries` deletes the entry; `sendPending` writes both once `deliver` returns. A redelivered task continues the attempt count instead of starting a second chain. `deliver` sends the reply: ```ts // managed/agent.ts async deliver(text, via) { if (text.trim() === "") return; // nothing to say is not a message const telnyx = this.env.TELNYX; if (!telnyx) throw new Error(`replying on ${via.kind === "email" ? "an email inbox" : "a messaging profile"} needs the TELNYX binding ([telnyx] in telnyx.toml)`); if (via.kind === "messaging") { await telnyx.messages.send({ from: via.to, to: via.from, text, messaging_profile_id: via.profileId }); } else { // The inbox reply action: recipients, In-Reply-To and References come from the message it answers. await telnyx.post(`/email_inboxes/${encodeURIComponent(via.inboxId)}/messages/${encodeURIComponent(via.messageId)}/actions/reply`, { body: { text } }); } } ``` `this.env.TELNYX` is the Telnyx binding of the instance's [`env`](/docs/agent-sdk/interface/env), declared by `[telnyx]` in `telnyx.toml`. It holds no API key, and the runtime adds the credential before each request leaves. For a text the reply is sent from the number the text was sent to, back to the sender, on the same messaging profile. For an email the reply goes through the inbox's reply action on the message that came in, and the platform threads and addresses it. A `deliver` that throws never fails the run's task; the reply has a retry window of its own: ```ts // managed/agent.ts export const DELIVERY_TASK = "__telnyx_acp_deliver"; export const DELIVERY_RETRY_SECONDS = [30, 60, 120, 300, 600, 1200, 1800]; // about an hour in all private async sendPending(pending, attempt) { try { await this.deliver(pending.text, pending.via); } catch (err) { const status = httpStatus(err); // the API's status, or undefined for no answer const retry = retryableDelivery(status) && attempt <= DELIVERY_RETRY_SECONDS.length; const delay = retry ? DELIVERY_RETRY_SECONDS[attempt - 1] : undefined; console.log(JSON.stringify({ delivery: retry ? "failed" : "gave up", run: pending.runId, via: pending.via, attempt, status, error: err.message, retryInSeconds: delay })); if (!retry) { await this.setState({ pendingDeliveries: { [runId]: null }, deliveryErrors: { [runId]: { …, final: true } } }); return; } await this.setState({ deliveryErrors: { [runId]: { …, nextAt: this.now() + delay * 1000 } } }); await this.schedule(delay, DELIVERY_TASK, { runId: pending.runId, attempt: attempt + 1 }); return; } await this.setState({ deliveredRuns: [...deliveredRuns, runId], pendingDeliveries: { [runId]: null }, deliveryErrors: { [runId]: null } }); } ``` - `retryableDelivery` is true for no answer, a 429 or a 5xx; any other 4xx is final at once, since the API would refuse it again. - Each try is one log line, `delivery: "failed"` with `retryInSeconds` or `delivery: "gave up"`, with the channel, the target, the status and the API's reason. - `deliveryErrors[run.id]` in state says what stands between the person and that reply: `status`, `message`, `attempts`, `nextAt` while a try is due, `final` once given up. It is cleared when the reply goes out. (An agent deployed before this shape held one `pendingDelivery`/`deliveryError` slot; those are read as one entry and cleared by the next write.) - The `DELIVERY_TASK` fires through [`schedule()`](/docs/agent-sdk/interface/schedule) and arrives at `onTask`, which [The Run](/docs/agent-sdk/inside/turn-taking/run) shows; `retryDelivery` finds the `pendingDelivery` for that run and calls `sendPending` with the next attempt. A reply that went out in the meantime, or a run that already delivered, is not delivered twice. - The window spent is final too: after the seventh wait the pending entry is dropped and `final` is set on its error. - A run whose approval expired is reconciled by `ready()` after `recover()`: it gets `failedRunId` and `lastError`, and its `replyTo` entry is forgotten, so the state stream shows the outcome. A reply to `invoke` or `chat` is never delivered anywhere, since it had no channel. It is read from the state stream. `deliver` is overridable, which is how a class changes where replies go. --- ### The Voice Loop > Source: https://developers.telnyx.com/docs/agent-sdk/inside/turn-taking/voice-loop.md ```text {16,17,18} support-agent/ ├── agent.json ├── instructions.md └── .telnyx/ written by deploy ├── index.ts ├── telnyx.toml ├── telnyx-env.d.ts └── package.json @telnyx/acp/ the package ├── managed/ │ ├── index.ts │ ├── agent.ts │ ├── model.ts │ ├── memory.ts │ ├── tools.ts │ ├── mcp.ts │ ├── voice.ts ◀ │ ├── direct-turn.ts ◀ │ └── filler.ts ◀ ├── channels/ │ ├── index.ts │ ├── phone.ts │ ├── email.ts │ ├── web.ts │ └── wire.ts ├── synth/ │ ├── index.ts │ ├── code-entry.ts │ └── vendor.ts └── spec/ ├── schema.ts ├── model.ts ├── phone.ts ├── project.ts └── io.ts ``` A call does not pass through `admit`. The `voice()` mixin from [`@telnyx/edge-runtime/voice`](/docs/agent-sdk/runtime-sdk) runs STT and TTS, takes each end of turn from STT, and asks the class for one thing per utterance, a turn engine. By default that is the direct engine in `managed/direct-turn.ts`. The turn goes straight to the model with the conversation held in memory, and the confirmed exchange is written behind the call. With `voice.harness` true the harness itself is the engine. Each turn then runs the harness's model and tools as a direct turn, not as a persistent run, at the cost of a second or more before the first word. `defineManagedVoiceAgent` in `managed/voice.ts` wraps the managed class in the mixin: ```ts // managed/voice.ts export function defineManagedVoiceAgent(spec, host = {}) { const Base = defineManagedAgent(spec, host); class ManagedVoiceAgent extends voice(Base) { greeting(call) { this.nameCaller(call.from); // the caller's number names their memory profile; the summary read starts here return defaultGreeting(spec); } // turnEngine, speechProviders, reply, turnEnded, callEnded, warmCall … } return ManagedVoiceAgent; } ``` The mixin answers the call, runs barge-in and the keypad, and ends the call. The class overrides its hooks, and adds `warmCall` of its own. - `warmCall` runs before the call is answered, as [The Call Webhook](/docs/agent-sdk/inside/request-handling/call-webhook) shows. - `greeting` is spoken when the call is answered. The mixin's own says nothing. - `turnEngine` returns the engine above. The mixin's own returns none. - `speechProviders` builds the STT and TTS providers from `spec.voice`. - `reply` wraps the mixin's own reply in `withFiller` from `managed/filler.ts`. When the caller is confirmed done and `voice.filler.afterMs` pass without a word from the model, one short phrase is spoken as its own sentence, and the reply follows. The phrase is said, never written, so it reaches neither the message log nor the caller's memory. - `turnEnded` logs the turn's clock and writes the exchange to the [message log](/docs/agent-sdk/interface/messages) after the reply has finished playing. - `callEnded` writes the last reply to state with [`setState()`](/docs/agent-sdk/interface/setState) and, with memory on, pushes the call to Agent Memory under its id. Each turn reaches the engine through `reply`: ```ts // managed/voice.ts reply(transcript, call) { const base = super.reply(transcript, call); if (!this.filler) return base; // …the same reply, wrapped in withFiller } // … turnEngine() { const self = this; if (harnessOnCalls(spec)) return self.ready({ calls: true }); return (this.direct ??= createDirectTurnEngine({ model: voiceModel(spec, host, self.env), // …instructions, history and record })); } ``` `super.reply(transcript, call)` is the mixin's own `reply`, which hands the transcript to the engine that `turnEngine()` returns. - `transcript` is STT's first pass at the caller's words, and `call.confirmed` resolves to the confirmed words. - While the turn is speculative, the mixin calls the engine's `begin()` with the first pass, then commits the confirmed words or discards the turn. - Otherwise it calls the engine's `turn()` with the confirmed words, and the result's `text` is spoken. - A reply the caller cuts short is still a turn. The direct engine remembers the caller's words and what was said of the reply before the cut, with the note `[cut off by the caller]` after it, in its history and in the journal; once playback reports what the caller heard, the entry is corrected to that. The next turn's context holds both, so an interrupted "Sure, what is the new…" and the caller's "12 Main St" line up. With `voice.harness` true the engine is `ready({ calls: true })`, the recovered harness for calls, and both calls are its own. That harness leaves out every tool marked `ask`, since a call cannot wait for an approval; without any `ask` it is the same instance texts use. - [`begin()`](/docs/agent-sdk/harness-sdk/harness/begin) streams provisional text, with no writes or tools until the turn is committed. - [`turn()`](/docs/agent-sdk/harness-sdk/harness/turn) runs the input to completion and records the turn in the message log. By default the direct engine answers both calls itself, with the AI SDK's `streamText` and no harness. Over the mount, the voice class is the managed class unchanged except for [`webSocket()`](/docs/agent-sdk/interface/webSocket), which answers an upgrade marked `?media=call` with the voice layer and hands every other socket to the agent socket protocol as the managed class would, with the same six RPC methods. [Extending the Managed Agent](/docs/agent-sdk/extending#the-voice-hooks) has the hooks' signatures. --- ### Extending the Managed Agent > Source: https://developers.telnyx.com/docs/agent-sdk/extending.md `@telnyx/acp/managed` exports the classes the CLI generates for a configuration project. A code-based agent extends them. | Export | What It Is | |---|---| | `defineManagedAgent(spec, host?)` | A class bound to the spec: the managed loop for texts and `invoke`. | | `defineManagedVoiceAgent(spec, host?)` | The same, wrapped in the `voice()` mixin from [`@telnyx/edge-runtime/voice`](/docs/agent-sdk/runtime-sdk), which answers calls. | | `ManagedAgent` | The loop itself, for a class that builds its own host in the constructor. | | `ReplyVia`, `ManagedAgentSpec`, `ManagedAgentHost` | The types. | Every class is a runtime SDK [`Agent`](/docs/agent-sdk/runtime-sdk), so [`this.messages`](/docs/agent-sdk/interface/messages), [`getState()`](/docs/agent-sdk/interface/getState) and [`setState()`](/docs/agent-sdk/interface/setState), [`queue()`](/docs/agent-sdk/interface/queue), [`schedule()`](/docs/agent-sdk/interface/schedule), [`@rpc`](/docs/agent-sdk/interface/rpc) methods and the rest of its API are there to use. ## The Host The second argument is what `agent.json` cannot say: ```ts import { ManagedAgent, type ManagedAgentHost, type ManagedEnv } from "@telnyx/acp/managed"; import type { ActorContext } from "@telnyx/edge-runtime"; import { tool } from "ai"; import { z } from "zod"; const spec = { name: "support-agent", model: "zai-org/GLM-5.3-Flash", instructions: "…", approvals: { refund_order: "ask" } } as const; const host: ManagedAgentHost = { tools: { refund_order: tool({ description: "Refund an order", inputSchema: z.object({ orderId: z.string() }), execute: async ({ orderId }) => ({ refunded: orderId }), }), }, authorization: myAuthorizationProvider, // who may approve; without it the default allows every decision under the agent's own identity approvalTtlMs: 15 * 60 * 1000, // how long a granted approval stays usable (5 min to 24 h) }; export class SupportAgent extends ManagedAgent { constructor(ctx: ActorContext, env: ManagedEnv) { super(ctx, env, spec, host); } } ``` | Host Field | Meaning | |---|---| | `tools` | A tool set, in the `ai` package's shape. `spec.approvals` marks each tool. An `ask` tool pauses the run until `approve` or `deny`, and a `deny` tool is withheld. | | `authorization` | Identity and policy for approvals, registered as the harness's [authorization port](/docs/agent-sdk/harness-sdk/ports/authorization). | | `approvalTtlMs` | 5 minutes to 24 hours. | | `model` | A language model used outright, instead of `spec.model` over the platform. | | `completions` | Chat completions for `spec.model`, when the platform's endpoint is not the right one. | | `environmentKeys` | Which bindings cross into the harness ports' [`environment`](/docs/agent-sdk/harness-sdk/ports/environment) (none by default). | | `authorize(token, req)` | Who may read the streams and call `@rpc` methods over the mount. Everyone, unless the class narrows it. | ### Approvals, End to End A run that reaches a tool marked `ask` pauses, and the state records the paused run as `awaitingApprovalRunId`; `invoke` ends with a line naming that run instead of waiting. Under `dev`, the line also carries the approval's id. A decision is one RPC on the conversation: ```bash telnyx-acp rpc support-agent --conversation alice inspectApproval telnyx-acp rpc support-agent --conversation alice approve telnyx-acp rpc support-agent --conversation alice deny ``` Under `dev`, approvals are authorized by a fixed local identity that allows every decision, and a paused run is printed with the `rpc … --local approve ` line to decide it. Deployed, a host that passes no `authorization` gets the loop's built-in default: every decision is allowed, under the agent's own identity (`agent:`), so whoever the mount admits to `rpc` decides (currently everyone). Pass `authorization` to require a real caller identity and policy; the harness itself refuses a run with an `ask` tool when no provider is registered at all. ## What to Override ```ts import { defineManagedAgent, type ReplyVia } from "@telnyx/acp/managed"; import { rpc } from "@telnyx/edge-runtime"; export class SupportAgent extends defineManagedAgent(spec) { /** Where a reply goes out. The default sends a text on the profile the message came in on. */ protected override async deliver(text: string, via: ReplyVia): Promise { await super.deliver(text, via); await this.queue("audit", { text }); // the class's own persistent follow-up } /** An RPC of the class's own, reachable over the mount and with `telnyx-acp rpc`. */ @rpc({ description: "The last reply" }) async lastReply(): Promise { return (await this.getState()).lastReply; } protected override async onTask(name: string, payload: unknown, info: { attempt: number }): Promise { if (name === "audit") return; // handle the class's own; everything else is the loop's await super.onTask(name, payload, info); } } ``` The loop keeps its six `@rpc` methods, `receive`, `approve`, `deny`, `inspectApproval`, `pendingApproval` and `run`. Methods without `@rpc` are private over the mount, which is how the webhook handler's `receiveVia` (which names where a reply goes) is reachable in-process only. ## The Voice Hooks `defineManagedVoiceAgent(spec)` answers calls. Its hooks, all overridable: | Hook | When | Default | |---|---|---| | `greeting(call)` | the call is answered | `spec.voice.greeting`, or "Hi, this is <name>. How can I help?" | | `turnEngine()` | each turn | the direct engine (model + in-memory history); the harness with `voice.harness` | | `reply(transcript, call)` | each reply | the mixin's reply wrapped in `withFiller`, which says one short phrase when the model is slow to start, tuned by `voice.filler` | | `speechProviders()` | the call starts | STT and TTS, tuned from `spec.voice` | | `turnEnded(metrics, call)` | a turn's playout ends | logs the turn's clock, writes the exchange | | `callEnded(call, reason)` | hang-up | writes the last reply, ingests the call into memory | | `warmCall(from?)` | before the call is answered | starts the instance, names the caller, begins the first turn's reading | `call.from` and `call.to` are the numbers, `call.callControlId` the call. [The Voice Loop](/docs/agent-sdk/inside/turn-taking/voice-loop) shows how the class drives the mixin. ## Dropping to the SDK A class that extends the runtime SDK's `Agent` directly, or `voice(Agent)`, is also a valid entry. The CLI deploys any exported agent class and wires the declared channels to it, and the loop is left to the user. The webhook handlers then call `receiveVia(text, from, key, via)` on that class for a text and open the media socket to it for a call. A class of the user's own implements them as the managed loop does, or as [Bring Your Own Framework](/docs/agent-sdk/examples/bring-your-own-framework) shows. --- ### The Package > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk.md The Agent Harness SDK is the package `@telnyx/agent-harness`. Its export is `createHarness(spec)`, which builds a harness from `spec`. Anything that implements the turn taking drives the harness. The harness never touches the runtime directly. It dictates what it needs from the runtime layer through the ports contract, and whatever implements the contract can host the harness; see [Ports](/docs/agent-sdk/harness-sdk/ports) for detail. | Export | What it is | |---|---| | `@telnyx/agent-harness` | `createHarness`, the ports contract, and the runtime adapter that builds ports from an instance of the Agent Runtime SDK's [`Agent`](/docs/agent-sdk/runtime-sdk) class, and a generic channel contract for discrete-message channels. | | `@telnyx/agent-harness/node` | A plain-Node ports adapter for tests, in memory with a file-backed SQLite database. | | `@telnyx/agent-harness/contract` | The executable ports contract, version 2, that any host adapter must pass. | | `@telnyx/agent-harness/tools` | Built-in tool sets over Telnyx platform APIs: [`browserTools()`](/docs/agent-sdk/harness-sdk/tools/browser). | | `@telnyx/agent-harness/channels` | Channel adapters over live providers: [`emailChannel()`](/docs/agent-sdk/harness-sdk/channels/email-adapter). | The pages document the harness in three parts. **The Interface** is what is exposed to the layer above, the call that builds a harness and the harness it returns. | Group | What it is for | |---|---| | [createHarness()](/docs/agent-sdk/harness-sdk/create-harness) | Build a harness from a spec. | | [Turns](/docs/agent-sdk/harness-sdk/harness/turn) | Run one input through the model and the tools. | | [Runs](/docs/agent-sdk/harness-sdk/harness/accept) | Admit inputs as persistent runs, execute and recover them, and decide their approvals. | **Plug-ins** are the parts the package ships for plugging into the harness. | Plug-in | What it is for | |---|---| | [Virtual Workspace](/docs/agent-sdk/harness-sdk/plug-ins/workspace) | Give the model a per-instance text store with skills, as tools. | | [Scheduling](/docs/agent-sdk/harness-sdk/plug-ins/scheduling) | Let the model schedule its own follow-ups. | | [Middleware](/docs/agent-sdk/harness-sdk/plug-ins/middleware) | Wrap a turn, a model step or a tool call. | | [Browser tools](/docs/agent-sdk/harness-sdk/tools/browser) | Give the model a web browser over Agent Browser, as tools. | **The Internals** is how the harness is implemented over the ports contract. | Group | What it is | |---|---| | [Ports](/docs/agent-sdk/harness-sdk/ports) | What the harness requires from the runtime. | | [Adapters](/docs/agent-sdk/harness-sdk/adapters/runtime) | Implementations of the ports contract, and the suite that checks one. | | [Persistence](/docs/agent-sdk/harness-sdk/persistence/run-ledger) | The run ledger and the step memo behind persistent runs. | | [Channels](/docs/agent-sdk/harness-sdk/channels/router) | A generic contract for discrete-message channels, and the email adapter. | `@telnyx/agent-harness` is at 0.1.0-beta.3. It depends on `@telnyx/edge-runtime` `^0.16.1` and requires Node 22.13 or later. Its tools are AI SDK tools from `ai` (`^6.0.266`); a tool set built with another major version of `ai` does not type-check against it. --- ### createHarness() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/create-harness.md ## spec.ports ## spec.model Any AI SDK provider supplies the model. A failed call to it surfaces as [`HarnessProviderError`](/docs/agent-sdk/harness-sdk/harness/turn#harnessprovidererror), which keeps only allow-listed diagnostics. ## spec.models The [runtime configuration](#runtime-configuration) selects one for a turn by its name. ## spec.tools Tools are keyed by the name the model calls them by. `createHarness()` throws a `TypeError` unless every tool follows these rules. - It has an `execute` function. - It is an ordinary function tool, not a dynamic or provider tool. - It sets `needsApproval` only to `true`. - It uses no deferred results, no `toModelOutput` and none of the `onInput` hooks. A tool with `needsApproval: true` runs only inside a persistent run. A direct `turn()` whose tools include one throws `TypeError("Harness approval-capable tools require durable runs")`. Such a turn starts with [`accept()`](/docs/agent-sdk/harness-sdk/harness/accept) and executes through [`run()`](/docs/agent-sdk/harness-sdk/harness/run). ## spec.activeTools When it is given, only the named tools are offered to the model. The [runtime configuration](#runtime-configuration) can offer another subset for a turn. ## spec.authorization Both fields are required when any tool sets `needsApproval`. `createHarness()` throws a `TypeError` when a rule is broken. - `toolActions` maps each tool in `spec.tools` to an action, and names no other tool. - An action is one or more runs of letters and digits joined by dots, such as `orders.refund`, at most 512 bytes. - `approvalTtlMs` is an approval's lifetime from its request, in milliseconds, from 300000 (5 minutes) to 86400000 (24 hours). [`approvals`](/docs/agent-sdk/harness-sdk/harness/approvals) decides each held call. ## spec.instructions The text is the model's system prompt on every step. The harness assembles nothing into it, so its content is decided before the harness is built. - [`assemblePrompt()`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#assembleprompt) on a virtual workspace builds it from a base text and skills. - The [runtime configuration](#runtime-configuration) replaces it for a turn. ## spec.output `output` is an AI SDK output definition, such as `Output.object({ schema })` from `ai`. The model's final text is parsed through it, and the parsed value is returned as `output` in the [`HarnessTurnResult`](/docs/agent-sdk/harness-sdk/harness/turn#harnessturnresult), beside `text`. A harness with `output` or `outputs` cannot take [`begin()`](/docs/agent-sdk/harness-sdk/harness/begin) turns. ## spec.outputs The [runtime configuration](#runtime-configuration) selects one for a turn by its name. ## spec.limits `steps` is a positive integer that bounds the model steps of one turn. When the last allowed step still calls a tool, the turn throws [`HarnessStepLimitError`](/docs/agent-sdk/harness-sdk/harness/turn#harnesssteplimiterror). The [runtime configuration](#runtime-configuration) can replace it for a turn. ## spec.middleware Each list wraps one phase of a turn. - `turn` wraps the whole turn. - `modelStep` wraps each call to the model, and requires a model object rather than a model id. - `tool` wraps each tool execution. A list runs in its given order, its first entry outermost. An entry that does not call `next` ends the phase with its own result. A harness with `turn` or `modelStep` middleware cannot take [`begin()`](/docs/agent-sdk/harness-sdk/harness/begin) turns. [`HarnessMiddleware`](/docs/agent-sdk/harness-sdk/plug-ins/middleware) documents the contexts. ## spec.durability A host leaves `durability` unset. Its seams exist for recovery tests. ## Runtime Configuration At the start of every turn, the harness reads one key of the instance's state, `__telnyx_agent_harness`, and resolves the turn's configuration from it. ```ts await this.setState({ __telnyx_agent_harness: { config: { model: "fast", limits: { steps: 4 } } }, }); ``` - `model` and `output` name an entry of `spec.models` and `spec.outputs`. - `instructions` replaces the static text. - `tools` names the tools offered, from `spec.tools`, in place of `spec.activeTools`. - `limits.steps` replaces the step limit. Every field is optional, and a field left out or `null` takes its static value. A value that does not validate, such as one with an unknown name or key, is ignored whole, and the last valid configuration stands. --- ### turn() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/turn.md ## HarnessTurnOptions ## HarnessTurnResult ## HarnessUsage ## HarnessStep ## HarnessStepLimitError ## HarnessProviderError ## HarnessProviderDiagnostics ## HarnessToolOutputError ## HarnessCancellationError ## HarnessObserverError --- ### begin() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/begin.md ## HarnessSpeculativeTurn ## HarnessSpeculationConflictError ## HarnessSpeculationUnsupportedError --- ### accept() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/accept.md ## HarnessRunAcceptance ## HarnessRunAcceptanceOptions `key` is the required idempotency key. It is a non-blank string of at most 512 bytes. A repeat call with the same key and the same input returns the existing run with `duplicate` set to `true`. A repeat call with the same key and different input throws. `admit` is an optional admission check. It runs inside the admission transaction, after the key lookup and before the run is inserted. When it returns `false`, no run is inserted and `accept()` rejects. `journalSeq` is an optional actor-journal sequence. The harness records it as the run's journal boundary before the run executes. It must be a non-negative safe integer, and any other value throws. --- ### dispatch() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/dispatch.md --- ### run() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/run.md --- ### recover() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/recover.md --- ### get() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/get.md ## HarnessRun --- ### status() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/status.md ## HarnessRunStatus | Status | Meaning | |---|---| | `accepted` | Admitted, and waiting for its task. | | `running` | Executing in a task. | | `awaiting_approval` | Paused on a tool call that needs approval. | | `resume_pending` | Its approvals decided, and waiting for the task that continues it. | | `completed` | Finished, with its reply in the message log. | | `failed` | Ended by an error, which `failureCode` classifies, such as `HARNESS_STEP_LIMIT`. | | `canceled` | Ended by `cancel()`. | | `outcome_unknown` | Interrupted or canceled while a tool call was under way. | ## HARNESS_RUN_STATUSES --- ### list() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/list.md ## HarnessRunListOptions --- ### cancel() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/cancel.md --- ### approvals > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/harness/approvals.md ## inspect() ## grant() ## deny() ## Required Actions Each decision is checked against the [authorization port](/docs/agent-sdk/harness-sdk/ports/authorization), which must allow one action. Without the port, every decision fails closed. | Operation | Action | |---|---| | `inspect()` | `agent_harness.approvals.read` | | `grant()` | `agent_harness.approvals.grant` | | `deny()` | `agent_harness.approvals.deny` | | The approved call | The tool's action from [`toolActions`](/docs/agent-sdk/harness-sdk/create-harness#spec-authorization) | ## HarnessApproval ## HarnessApprovalStatus | Status | Meaning | |---|---| | `pending` | Requested and undecided. | | `granted` | Approved, and usable until `expiresAt`. | | `denied` | Refused. | | `expired` | Not decided, or not used, within its lifetime. The run then fails with `failureCode` `HARNESS_APPROVAL_EXPIRED`. | | `consumed` | Used by the call it approved. | ## HARNESS_APPROVAL_STATUSES ## HarnessAuthorizationError | Code | Meaning | |---|---| | `identity_unavailable` | There is no authorization port, or it gives no identity. | | `unauthenticated` | The identity names no Service Account or organization. | | `forbidden` | The policy denies the action. | | `policy_unavailable` | The policy gives no decision. | ## HarnessApprovalError | Code | Meaning | |---|---| | `expired` | Its lifetime has passed. | | `replayed` | The same decision is already recorded. | | `conflicting` | The opposite decision is already recorded. | | `consumed` | The approved call has already executed. | | `missing` | The approval record the decision needs does not exist. | --- ### createVirtualWorkspace() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/plug-ins/workspace.md ## createVirtualWorkspaceTools() | Tool | Effect | |---|---| | `read_file` | Reads a file, cut at `maxOutputBytes` and then marked `truncated`. | | `write_file` | Writes a file. With `expectedRevision`, only while the file is at that revision. | | `edit_file` | Replaces a text that occurs exactly once in a file, under the same guard. | | `list_files` | Lists the files in path order. | | `find_files` | Lists the files whose content contains a text. | | `grep_files` | Returns the lines that contain a text, with their paths and line numbers. | | `activate_skill` | Returns one skill's document as data. | The results of the file tools carry `origin: "workspace"`, and the result of `activate_skill` carries `origin: "activated-skill"`. A path is relative, such as `notes/order.md`, and at most 128 bytes. ## read() ## write() ## edit() ## list() ## find() ## grep() ## journal() ## discoverSkills() A skill is the document at `skills//SKILL.md`, written like any other file. Nothing in a skill is executed. ## activateSkill() ## assemblePrompt() ## VirtualWorkspaceLimits | Limit | Default | Bounds | |---|---|---| | `maxFileBytes` | 64 KiB | One file. | | `maxWorkspaceBytes` | 1 MiB | Every file together. | | `maxOutputBytes` | 16 KiB | One result, the assembled prompt included. | | `maxResults` | 100 | The entries of one listing or search. | ## WorkspaceEntry ## WorkspaceRead ## WorkspaceWriteOptions ## WorkspaceJournalEntry ## WorkspaceSkill ## WorkspaceSkillCatalog ## ActivatedWorkspaceSkill ## PromptSource ## WorkspaceToolEntry ## ToolVirtualWorkspace --- ### createHarnessWithScheduling() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/plug-ins/scheduling.md ## createHarnessScheduling() ## schedule() ## listSchedules() ## cancelSchedule() ## dispatch() ## recover() ## tools ## HarnessSchedule ## HarnessScheduleRequest ## HarnessScheduleCancellation --- ### HarnessMiddleware > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/plug-ins/middleware.md ## runMiddleware() ## HarnessTurnMiddlewareContext ## HarnessModelStepMiddlewareContext ## HarnessToolMiddlewareContext ## HarnessMiddlewareError --- ### browserTools() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/tools/browser.md ## Over Agent Browser `browserTools()` is exported from `@telnyx/agent-harness/tools`, from 0.1.0-beta.3. The tools call [Agent Browser](/docs/agent-browser) through `transport`, the Telnyx API client; in a deployed function that is the `TELNYX` binding. ```ts import { createHarness } from "@telnyx/agent-harness"; import { browserTools } from "@telnyx/agent-harness/tools"; const harness = createHarness({ ports, model, limits: { steps: 8 }, tools: { ...browserTools({ transport: env.TELNYX }), }, }); ``` | Tool | Effect | |---|---| | `browser_open` | Opens a URL and returns the page. Opening the URL the session is on reads the page again without reloading it. | | `browser_click` | Clicks an element by its ref and returns the resulting page. | | `browser_fill` | Types a value into an input by its ref, replacing its content. The value is never logged. | | `browser_select` | Chooses an option of a dropdown by its ref, by the option's value or label. | | `browser_press` | Presses one of [`BROWSER_KEYS`](#browser_keys). `Enter` submits the focused form. | | `browser_scroll` | Scrolls by `dy` pixels, from `-5000` to `5000`, and returns what is in view. | | `browser_screenshot` | Takes a screenshot and returns its `artifactId`, `downloadUrl`, `contentType` and `bytes`. The model does not see the image. | A page is a [`BrowserPage`](#browserpage): the URL, the title, the element refs (`e13: link "Learn more"`) and the text tree, cut at 20,000 characters and 300 refs. A stale observation is refreshed once. A ref that is gone is answered with the page read again. A failure, such as a link to another site or a site that refuses to load, comes back to the model as text, not as a failed run. ## Sessions - **Per run.** Each durable run holds at most one [session](/docs/agent-browser/sessions), keyed by the run's id. The tools learn the run from the harness; the host wires nothing. A run paused for approval keeps its session until it ends. - **Per site.** The session's domain policy is the host of the first URL the model opens and its subdomains, plus the bare host when the URL starts with `www.` (see [`siteDomains()`](#sitedomains)). Opening another site closes the session and opens one for that site. `browser_open` waits up to 45 seconds for a new session to be ready. - **Cleanup.** The session is closed when the run ends: completed, failed or canceled. The harness operation that ended the run waits for the close for at most 10 seconds, the harness's run-end timeout. If the API does not answer within it, the operation returns with the session possibly live, and the session's idle timeout (`idleTimeoutS`) or lifetime (`lifetimeS`) ends it. - **Reopen.** A session the platform ended is reopened once per run. - **Without a run.** Under a plain [`turn()`](/docs/agent-sdk/harness-sdk/harness/turn) the tools share one session, which only its idle timeout closes. - **Budget.** A run takes at most `actions` browser actions, 40 by default. ## BrowserToolsOptions ## BrowserTransport ## BrowserPage ## BrowserObservation ## browserToolNames() ## BROWSER_TOOL_NAMES ## BrowserToolName ## BROWSER_KEYS ## siteDomains() ## trimPage() ## DEFAULT_BROWSER_ACTIONS ## BROWSER_LIFETIME_DEFAULT_S ## BROWSER_IDLE_TIMEOUT_DEFAULT_S ## BROWSER_TREE_MAX_CHARS ## BROWSER_MAX_REFS --- ### The Contract > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports.md A port is one capability of the runtime behind an interface the package defines. `ports` is the full set, `AgentHarnessPorts` version 2 of the contract, and it is the runtime plugged into the harness. The harness reaches the instance's storage and scheduler only through it. The raw environment, the actor context and the actor storage never cross the boundary. | Port | What it is | |---|---| | `identity` | The instance's id, asserted by the host and never taken from an input. | | `activation` | An opaque token, stable for one live activation of the instance. | | `clock` | The host's clock, used by queue and schedule operations. | | `messages` | The message log, with `append`, `appendMany`, `all`, `last` and `count`. | | `state` | The state, with `get`, `merge` and `replace`. | | `events` | The event log, with `emit`, `read` and `count`. | | `tasks` | The task scheduler, with `queue`, `schedule`, `every`, `cancel` and `list`, delivered at least once. | | `sql` | The per-instance SQL surface, `exec` and `transactionSync`. | | `environment` | An explicitly selected, immutable bag of bindings. Nothing crosses by default. | | `authorization` | The gateway-attested identity and policy that approval decisions require. Optional, and approvals fail closed without it. | On the Agent Runtime, [the runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the ports from members of the [`Agent`](/docs/agent-sdk/runtime-sdk) class. ## Building Ports `createRuntimeAgentHarnessPorts(agent, { environmentKeys })` builds the ports from an instance of the Agent Runtime SDK's [`Agent`](/docs/agent-sdk/runtime-sdk) class, through a seam the runtime owns and without reflecting over the class. `environmentKeys` names the bindings that cross into `environment`, and none do unless named. For tests, `createNodeAgentHarnessPorts(options)` from `@telnyx/agent-harness/node` is a deterministic plain-Node implementation, in memory for the log, state, events and tasks, and file-backed through `node:sqlite` for SQL. `defineAgentHarnessPortsContract(label, factory)` from `@telnyx/agent-harness/contract` registers the shared contract suite against any adapter, so a host of the user's own is checked against the same semantics as the runtime's. The contract module imports `vitest`, an optional peer dependency, so `vitest` must be installed wherever the suite runs. The suite asserts fixed fixture values. The factory's ports must report the identity id `"contract-agent"`, a clock reading of `1_700_000_000_000` and the environment `{ MODEL: "deterministic-model" }`. --- ### ports.messages > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/messages.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const last = ((count) => count === undefined ? host.messages.last() : host.messages.last(count)); const messages = Object.freeze({ append: (message) => host.messages.append(message), appendMany: (batch) => host.messages.appendMany(batch), all: () => host.messages.all(), last, count: () => host.messages.count(), }); ``` - `append()` calls [`this.messages.append()`](/docs/agent-sdk/interface/messages#append), which assigns the message's `seq` and writes its row in one commit. - `appendMany()` calls [`this.messages.appendMany()`](/docs/agent-sdk/interface/messages#appendmany), which commits the whole batch together. - `all()` calls [`this.messages.all()`](/docs/agent-sdk/interface/messages#all), which returns the whole history in order. - `last()` calls [`this.messages.last()`](/docs/agent-sdk/interface/messages#last), with the count when one is given. - `count()` calls [`this.messages.count()`](/docs/agent-sdk/interface/messages#count). The log is append-only, so the count is also the `seq` of the last message. - [`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage) and [`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage) are the runtime SDK's own types. ## AgentHarnessMessagePort --- ### ports.state > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/state.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const state = Object.freeze({ get: () => host.getState(), merge: (patch) => host.mergeState(patch), replace: (next) => host.replaceState(next), }); ``` - `get()` calls [`getState()`](/docs/agent-sdk/interface/getState). Until a state is written, it returns [`initialState()`](/docs/agent-sdk/interface/initialState). - `merge()` calls [`setState()`](/docs/agent-sdk/interface/setState), which `host` carries as `mergeState`. The patch follows RFC 7396, so `null` deletes a key. - `replace()` calls [`replaceState()`](/docs/agent-sdk/interface/replaceState). Nothing of the previous state survives. - `merge()` and `replace()` run the class's [`onStateChanged()`](/docs/agent-sdk/interface/onStateChanged) after the write commits. ## AgentHarnessStatePort --- ### ports.events > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/events.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const events = Object.freeze({ emit: (type, payload) => host.events.emit(type, payload), read: (afterSeq, limit) => host.events.read(afterSeq, limit), count: () => host.events.count(), }); ``` - `emit()` calls [`this.events.emit()`](/docs/agent-sdk/interface/events#emit), which assigns the event's `seq` and writes its row in one commit. - `read()` calls [`this.events.read()`](/docs/agent-sdk/interface/events#read). `afterSeq` is exclusive, and only retained events are returned. - `count()` calls [`this.events.count()`](/docs/agent-sdk/interface/events#count), the number of events ever emitted. It includes events already pruned. - [`StoredEvent`](/docs/agent-sdk/interface/events#storedevent) is the runtime SDK's own type. ## AgentHarnessEventPort --- ### ports.tasks > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/tasks.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const tasks = Object.freeze({ delivery: "at-least-once", queue: async (method, payload, scheduleOptions) => host.queue(method, payload, scheduleOptions), schedule: async (delaySeconds, method, payload, scheduleOptions) => host.schedule(delaySeconds, method, payload, scheduleOptions), every: async (intervalSeconds, method, payload, scheduleOptions) => host.every(intervalSeconds, method, payload, scheduleOptions), cancel: (id) => host.cancelSchedule(id), list: () => host.listSchedules(), }); ``` - `queue()` calls [`queue()`](/docs/agent-sdk/interface/queue), for a task due at once. - `schedule()` calls [`schedule()`](/docs/agent-sdk/interface/schedule), for a task due after a delay. - `every()` calls [`every()`](/docs/agent-sdk/interface/every), for a task that recurs at an interval. - `cancel()` calls [`cancelSchedule()`](/docs/agent-sdk/interface/cancelSchedule), which removes a pending task. - `list()` calls [`listSchedules()`](/docs/agent-sdk/interface/listSchedules), which returns a [`TaskRecord`](/docs/agent-sdk/interface/listSchedules#taskrecord) for every pending task. - With a stable `id` in its [`ScheduleOptions`](/docs/agent-sdk/interface/schedule#scheduleoptions), a call to `queue()`, `schedule()` or `every()` replaces the pending task with that id. - `delivery` declares the scheduler's own guarantee. A task survives crashes and restarts. It can be delivered more than once. - The harness's task names begin with `__telnyx_agent_harness_` and name no method of the class, so they reach [`onTask()`](/docs/agent-sdk/interface/onTask). Its default does nothing and counts the task as delivered. ## AgentHarnessTaskPort --- ### ports.sql > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/sql.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts sql: Object.freeze({ exec(query, ...bindings) { return host.sql.exec(query, ...bindings); }, transactionSync(fn) { return host.transactionSync(fn); }, }), ``` - `exec()` calls `exec()` on [`this.ctx.storage.sql`](/docs/agent-sdk/interface/ctx), the instance's own SQLite database. It rejects transaction-control statements such as `BEGIN`. - `transactionSync()` calls `this.ctx.storage.transactionSync()`. If its function throws, every statement the function ran is rolled back. ## AgentHarnessSqlPort --- ### ports.identity > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/identity.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const host = getAgentHarnessHost(agent); // … identity: Object.freeze({ id: host.id }), ``` - `id` is [`this.ctx.id`](/docs/agent-sdk/interface/ctx), the id the Agent Runtime assigned to the instance. ## AgentHarnessIdentity --- ### ports.clock > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/clock.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const host = getAgentHarnessHost(agent); // … clock: Object.freeze({ now: () => host.now() }), ``` - `now()` calls the class's [`now()`](/docs/agent-sdk/interface/now). The task scheduler reads time through the same method, so an override of `now()` sets the time for both. ## AgentHarnessClock --- ### ports.authorization > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/authorization.md ## On the Agent Runtime The [`Agent`](/docs/agent-sdk/runtime-sdk) class of the runtime SDK has no public member for authorization. [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) omits the port unless the host registers a provider for the instance through `setAgentHarnessAuthorizationProvider()`, from `@telnyx/edge-runtime/internal`. ```ts // runtime-adapter.ts import { getAgentHarnessHost, getAgentHarnessAuthorizationProvider } from "@telnyx/edge-runtime/internal"; // … const authorization = getAgentHarnessAuthorizationProvider(agent); // … ...(authorization === undefined ? {} : { authorization }), ``` A registered provider is passed through as the port. ## HarnessAuthorizationPort ## AgentHarnessAuthorizationIdentity --- ### ports.environment > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/environment.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the port from `host`, which carries the protected members of the `Agent` class. ```ts // runtime-adapter.ts const host = getAgentHarnessHost(agent); // … const environment = host.selectEnvironment(options.environmentKeys ?? []); // … environment, ``` - `environment` holds only the bindings of [`this.env`](/docs/agent-sdk/interface/env) that `environmentKeys` names, in a frozen object. --- ### ports.activation > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/activation.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) builds the token from the `Agent` object itself. ```ts // runtime-adapter.ts const activations = new WeakMap(); function activationFor(agent) { let activation = activations.get(agent); if (activation === undefined) { activation = Object.freeze({}); activations.set(agent, activation); } return activation; } ``` - The token is one frozen object per `Agent` object. Ports built twice on one object share it. - The Agent Runtime calls the [`constructor()`](/docs/agent-sdk/interface/constructor) on every activation. Each activation therefore has a new `Agent` object and a new token. - The harness keeps its in-memory claims on runs and steps per token. A new activation starts without them. --- ### ports.version > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/ports/version.md ## On the Agent Runtime [The runtime adapter](/docs/agent-sdk/harness-sdk/adapters/runtime#on-the-agent-runtime) takes `version` from the constant. No member of the `Agent` class is involved. ```ts // runtime-adapter.ts import { AGENT_HARNESS_PORTS_VERSION } from "./ports.js"; // … version: AGENT_HARNESS_PORTS_VERSION, ``` ## AGENT_HARNESS_PORTS_VERSION --- ### createRuntimeAgentHarnessPorts() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/adapters/runtime.md ## On the Agent Runtime `getAgentHarnessHost(agent)`, from `@telnyx/edge-runtime/internal`, hands the harness the protected members of the [`Agent`](/docs/agent-sdk/runtime-sdk) class. The harness therefore works on the same stores as the class's own methods. ```ts // runtime-adapter.ts import { getAgentHarnessHost, getAgentHarnessAuthorizationProvider } from "@telnyx/edge-runtime/internal"; import { AGENT_HARNESS_PORTS_VERSION } from "./ports.js"; // … export function createRuntimeAgentHarnessPorts(agent, options = {}) { const host = getAgentHarnessHost(agent); const authorization = getAgentHarnessAuthorizationProvider(agent); const environment = host.selectEnvironment(options.environmentKeys ?? []); // … messages, state, events and tasks const ports = { version: AGENT_HARNESS_PORTS_VERSION, identity: Object.freeze({ id: host.id }), activation: activationFor(agent), clock: Object.freeze({ now: () => host.now() }), ...(authorization === undefined ? {} : { authorization }), messages, state, events, tasks, sql: Object.freeze({ exec(query, ...bindings) { return host.sql.exec(query, ...bindings); }, transactionSync(fn) { return host.transactionSync(fn); }, }), environment, }; return Object.freeze(ports); } ``` | Port | Built from | |---|---| | [`messages`](/docs/agent-sdk/harness-sdk/ports/messages) | [`this.messages`](/docs/agent-sdk/interface/messages) | | [`state`](/docs/agent-sdk/harness-sdk/ports/state) | [`getState()`](/docs/agent-sdk/interface/getState), [`setState()`](/docs/agent-sdk/interface/setState) and [`replaceState()`](/docs/agent-sdk/interface/replaceState) | | [`events`](/docs/agent-sdk/harness-sdk/ports/events) | [`this.events`](/docs/agent-sdk/interface/events) | | [`tasks`](/docs/agent-sdk/harness-sdk/ports/tasks) | [`queue()`](/docs/agent-sdk/interface/queue), [`schedule()`](/docs/agent-sdk/interface/schedule), [`every()`](/docs/agent-sdk/interface/every), [`cancelSchedule()`](/docs/agent-sdk/interface/cancelSchedule) and [`listSchedules()`](/docs/agent-sdk/interface/listSchedules). The harness's tasks name no method of the class, so they reach [`onTask()`](/docs/agent-sdk/interface/onTask). | | [`sql`](/docs/agent-sdk/harness-sdk/ports/sql) | The instance's own SQLite database, [`this.ctx.storage.sql`](/docs/agent-sdk/interface/ctx), and `this.ctx.storage.transactionSync()` | | [`identity`](/docs/agent-sdk/harness-sdk/ports/identity) | The instance's id, [`this.ctx.id`](/docs/agent-sdk/interface/ctx) | | [`clock`](/docs/agent-sdk/harness-sdk/ports/clock) | [`now()`](/docs/agent-sdk/interface/now) | | [`environment`](/docs/agent-sdk/harness-sdk/ports/environment) | [`this.env`](/docs/agent-sdk/interface/env), restricted to the `environmentKeys` option | | [`activation`](/docs/agent-sdk/harness-sdk/ports/activation) | One frozen token per `Agent` object. The Agent Runtime constructs a new object on every activation, through the [`constructor()`](/docs/agent-sdk/interface/constructor). | | [`authorization`](/docs/agent-sdk/harness-sdk/ports/authorization) | No public `Agent` member. Omitted unless a provider is registered through `@telnyx/edge-runtime/internal`. | | [`version`](/docs/agent-sdk/harness-sdk/ports/version) | The constant `AGENT_HARNESS_PORTS_VERSION` | ## RuntimeAgentHarnessPortsOptions --- ### createNodeAgentHarnessPorts() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/adapters/node.md ## NodeAgentHarnessPorts ## NodeAgentHarnessPortsOptions --- ### defineAgentHarnessPortsContract() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/adapters/contract.md ## AgentHarnessPortsContractFixture ## AgentHarnessPortsContractFactory --- ### createHarnessRunLedger() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/persistence/run-ledger.md ## On the Agent Runtime The ledger records each run in the SQL port. It executes each run in a task of the tasks port. ```ts // run ledger (@telnyx/agent-harness) export function ensureHarnessDurabilitySchema(ports) { ports.sql.transactionSync(() => { ports.sql.exec("CREATE TABLE IF NOT EXISTS __telnyx_agent_harness_schema (version INTEGER PRIMARY KEY)"); // … }); } ``` - `ports.sql.exec()` runs on the instance's own SQLite database, [`this.ctx.storage.sql`](/docs/agent-sdk/interface/ctx). - `ports.sql.transactionSync()` is `this.ctx.storage.transactionSync()`. The schema is created and migrated in one such transaction. A migration that throws is rolled back whole. - The ledger's tables share the database with any table the class creates. Their names begin with `__telnyx_agent_harness_`. ```ts // run ledger (@telnyx/agent-harness) const TASK_METHOD = "__telnyx_agent_harness_run"; // … const enqueue = async (run) => { if (run.status !== "accepted") return; await ports.tasks.queue(TASK_METHOD, { runId: run.id }, { id: run.task_id, maxRetries: 5 }); }; // … const admission = ports.sql.transactionSync(() => { // … }); // This is intentionally outside the SQL transaction: a queue failure leaves an accepted record for recover(). await enqueue(admission.run); ``` - `accept()` queues the run's task after the run's row commits, through the class's [`queue()`](/docs/agent-sdk/interface/queue). - The task's `id` is the run's `task_id`. Queueing the run again, as `recover()` does, leaves one pending task for it. - `__telnyx_agent_harness_run` names no method of the class, so the task reaches [`onTask()`](/docs/agent-sdk/interface/onTask). The class overrides `onTask()` to hand it to [`dispatch()`](/docs/agent-sdk/harness-sdk/harness/dispatch). ## HarnessRunLedger ## HarnessRunLedgerOptions ## HarnessCheckpoint ## ensureHarnessDurabilitySchema() ## HarnessInjectedCrash ## HarnessApprovalPause --- ### createHarnessStepContext() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/persistence/step-context.md ## On the Agent Runtime The step memo is a table in the SQL port, written in transactions around the step's function. ```ts // steps.ts ports.sql.transactionSync(() => { const next = first(ports.sql.exec("SELECT COALESCE(MAX(journal_seq), 0) + 1 AS next FROM __telnyx_agent_harness_steps WHERE run_id = ?", options.runId).toArray()).next; ports.sql.exec("INSERT INTO __telnyx_agent_harness_steps(run_id,name,identity,input_fingerprint,version,status,output,journal_seq) VALUES (?,?,?,?,?,'prepared',NULL,?)", options.runId, name, identity, inputFingerprint, version, next); }); // … const output = await fn(); // … const serialized = serializeStepOutput(output, stepOptions.external === true); ports.sql.transactionSync(() => { ports.sql.exec("UPDATE __telnyx_agent_harness_steps SET status = 'completed', output = ?, output_failure = ? WHERE run_id = ? AND name = ?", serialized.output, serialized.failure, options.runId, name); }); ``` - `ports.sql.exec()` runs on the instance's own SQLite database, [`this.ctx.storage.sql`](/docs/agent-sdk/interface/ctx). The memo's table sits beside the run ledger's. - `ports.sql.transactionSync()` is `this.ctx.storage.transactionSync()`. A transaction that throws is rolled back whole. ## HarnessStepContext ## HarnessStepContextOptions ## HarnessStepOptions ## HarnessStepOutputSerializationError ## isToolOutputSerializationFailure() --- ### createChannelRouter() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/channels/router.md ## ChannelRouterOptions ## ChannelAdapter ## ChannelLedger ## OutboundChannelPolicy ## ChannelContent ## NormalizedChannelInbound ## ChannelAcceptance ## ChannelSendRequest ## ChannelReplyRequest ## ChannelOutboundRequest ## ChannelDeliveryEvent ## ChannelAuthorizationError --- ### InMemoryChannelLedger > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/channels/in-memory-ledger.md ## InMemoryChannelLedgerOptions --- ### SmsReferenceAdapter > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/channels/sms-reference-adapter.md ## SmsReferenceAdapterOptions --- ### emailChannel() > Source: https://developers.telnyx.com/docs/agent-sdk/harness-sdk/channels/email-adapter.md ## Over the Email API `emailChannel()` is exported from `@telnyx/agent-harness/channels`, from 0.1.0-beta.3. The adapter it returns is a [`ChannelAdapter`](/docs/agent-sdk/harness-sdk/channels/router#channeladapter) with `channel: "email"`, for [`createChannelRouter()`](/docs/agent-sdk/harness-sdk/channels/router). It handles the `email.received` webhook of an [inbox](/docs/messaging/email/inboxes). The host verifies the webhook's signature and passes its `data.payload` to `inbound()`. ```ts import { createChannelRouter, InMemoryChannelLedger } from "@telnyx/agent-harness"; import { emailChannel } from "@telnyx/agent-harness/channels"; const email = emailChannel({ transport: env.TELNYX, // the Telnyx client; paths are relative to /v2 inboxId: "inbox-id", onEvent: (event) => console.log(JSON.stringify(event)), }); const router = createChannelRouter({ adapters: [email], ledger: new InMemoryChannelLedger(), policy: { authorize: async () => true }, accept: async (inbound) => ({ runId: await startRun(inbound) }), }); // The webhook handler, after verifying the signature: const inbound = await email.inbound(webhook.data.payload); if (!inbound) return; // left alone: an event says why const { runId } = await router.receive(inbound); // Later, with the run's reply: await router.reply({ runId, serviceAccountId, idempotencyKey: runId, content: { text: "Sure, done.", messageId: inbound.content.messageId }, }); ``` - **Inbox.** The inbox is the payload's `inbox_id`. Without one, the adapter looks the recipient up in the account's inbox list (`GET /email_inboxes`), on `domainId` when it is set, and keeps the list per transport for 60 seconds. A mail for another inbox than `inboxId`, or to another address than `address`, is left alone. - **Matching.** The reply target is the inbox's record of the mail. The adapter lists the inbox's newest messages from the sender (`filter[from]`, `page[size]` 10) and takes the inbound one the one whose `id` or `message_id` equals the envelope's `id` or its RFC Message-ID (the live payload's `message_id_header`). A Message-ID is compared without its angle brackets. The adapter never matches by subject or recency. - **Text.** The text given to the model is the record's `reply_text`, else the plain-text body at `text_body_url` with its quoted history dropped, else the message read back from its thread. A body is fetched only over `https` from a host in `bodyHosts`, through the transport first and then with plain `fetch`. Redirects are never followed. - **Conversation.** `conversationId` is `email-`, else `email-`. `externalMessageId` is the envelope's `id`, which a redelivery repeats, so the router's ledger treats a redelivery as a duplicate. - **Reply.** `send()` posts `{ text }` to `POST /email_inboxes/{inbox}/messages/{message}/actions/reply` with the request's idempotency key as the `Idempotency-Key` header. The platform addresses and threads the reply. ## Unavailable mail `inbound()` throws [`EmailInboundUnavailableError`](#emailinboundunavailableerror) when the inbox has no record that matches the mail, and when a read it needs fails (the inbox list, the inbox, the body or the thread) and no other source has the text. The host answers the webhook with a non-2xx status, such as `503`, so the platform delivers it again. A mail that is not this adapter's, cannot be placed in an inbox or has no text returns `undefined`; a redelivery would end the same way, so the host acknowledges it. The platform redelivers a failed `email.received` webhook once, about one second later. ## EmailChannelOptions ## EmailAddressScope ## EmailTransport ## EmailChannelAdapter ## EmailChannelInbound ## EmailInboundContent ## EmailReplyContent ## EmailChannelEvent ## EmailChannelEventType ## EmailInboundUnavailableError ## emailConversation() ## stripQuotedEmail() ## isEmailBodyHost() ## EMAIL_BODY_HOSTS The value is `["telnyx.com", "telnyxstorage.com"]`. ## redactUrl() ## forgetEmailInboxCache() --- ### The Package > Source: https://developers.telnyx.com/docs/agent-sdk/runtime-sdk.md The Agent Runtime SDK is the package `@telnyx/edge-runtime`. Its export is the `Agent` class. Anything that implements the turn taking runs on the class. The class is hosted by the Agent Runtime Platform, which invokes it at its entry points; see [Entry Points](/docs/agent-sdk/contract/entry-points) for detail. | Export | What it is | |---|---| | `@telnyx/edge-runtime` | The `Agent` class, the `StatefulActor` it extends, and the types of the environment and its bindings. | | `@telnyx/edge-runtime/client` | `AgentClient`, documented as [The Agent Client SDK](/docs/agent-sdk/client-sdk). | | `@telnyx/edge-runtime/mount` | `mountAgents`, the function entry that serves every instance at one address. | | `@telnyx/edge-runtime/agent-socket` | `AgentSocketServer`, the server half of the agent socket protocol. | | `@telnyx/edge-runtime/agent-http` | `AgentHttpServer`, the streams and RPC over HTTP. | | `@telnyx/edge-runtime/voice` | The `voice()` mixin, with Telnyx STT and TTS for calls. | | `@telnyx/edge-runtime/internal` | Seams for trusted adapters, such as the harness's. Not for application code. | The pages document the `Agent` class in two parts. **The Interface** is what is exposed to the layer above, the class and what an instance has. | Group | What it is for | |---|---| | [Lifecycle](/docs/agent-sdk/interface/constructor) | Construct an instance with its options, and erase everything it holds. | | [Values](/docs/agent-sdk/interface/messages) | Reach the message log, the event log, the bindings and the actor context. | | [State](/docs/agent-sdk/interface/initialState) | Read and write the instance's persistent state, and react to its changes. | | [Tasks](/docs/agent-sdk/interface/queue) | Run work after the request returns, now, later or at an interval. | | [Children](/docs/agent-sdk/interface/spawn) | Create, list and end child instances. | | [Connections](/docs/agent-sdk/interface/authorize) | Decide who may connect, and receive the sockets and requests that arrive. | | [RPC](/docs/agent-sdk/interface/rpc) | Make a method callable over the address. | [Bring Your Own Framework](/docs/agent-sdk/examples/bring-your-own-framework) shows the glue code that runs any framework on the class. **The Internals** is how the class is served on the Agent Runtime Platform. | Group | What it is | |---|---| | [Entry Points](/docs/agent-sdk/contract/entry-points) | The methods the platform invokes on the class. | | [The Address and Transports](/docs/agent-sdk/contract/address-and-transports) | Where an instance answers, and over what. | | [Mount](/docs/agent-sdk/mounting-agents) | The function entry that serves every instance at one address. | | [AgentSocketServer](/docs/agent-sdk/internals/the-socket-server) | The server half of the agent socket protocol. | | [AgentHttpServer](/docs/agent-sdk/internals/the-http-server) | The streams and RPC over HTTP. | | [Limits](/docs/agent-sdk/limits) | The budgets, retries, storage and name lengths an instance works within. | --- ### constructor() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/constructor.md ## Type Parameters | Parameter | Constraint | Default | Meaning | |---|---|---|---| | `E` | `extends Env` | `Env` | The bindings, typed as `this.env`. | | `State` | `extends Record` | `Record` | The shape of the persistent state. | ## AgentOptions --- ### destroy() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/destroy.md --- ### messages > Source: https://developers.telnyx.com/docs/agent-sdk/interface/messages.md ## add() ## append() ## appendMany() ## all() ## last() ## count() ## toOpenAI() ## toAnthropic() ## toLangChain() ## new MessageLog() ## AgentMessage ## ToolCall ## StoredMessage --- ### events > Source: https://developers.telnyx.com/docs/agent-sdk/interface/events.md ## emit() ## read() ## count() ## new EventLog() ## StoredEvent ## EventLogOptions --- ### env > Source: https://developers.telnyx.com/docs/agent-sdk/interface/env.md --- ### ctx > Source: https://developers.telnyx.com/docs/agent-sdk/interface/ctx.md --- ### initialState() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/initialState.md --- ### getState() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/getState.md --- ### setState() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/setState.md --- ### replaceState() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/replaceState.md --- ### onStateChanged() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/onStateChanged.md --- ### queue() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/queue.md --- ### schedule() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/schedule.md ## ScheduleOptions --- ### every() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/every.md --- ### cancelSchedule() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/cancelSchedule.md --- ### listSchedules() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/listSchedules.md ## TaskRecord --- ### onTask() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/onTask.md --- ### now() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/now.md --- ### alarm() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/alarm.md --- ### spawn() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/spawn.md ## QuotaExceededError ### constructor ### code ### detail ### status --- ### children() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/children.md ## ChildRef --- ### despawn() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/despawn.md --- ### authorize() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/authorize.md ## Claim This is the `Agent` subclass's default. The generated managed agent instead defers to the host's `authorize` when one is set, and without one grants `["read", "rpc"]` — see [The Streams](/docs/agent-sdk/inside/request-handling/streams). --- ### onConnect() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/onConnect.md --- ### onAttach() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/onAttach.md ## Attachment --- ### attachments > Source: https://developers.telnyx.com/docs/agent-sdk/interface/attachments.md ## AgentAttachments --- ### connectionEngine > Source: https://developers.telnyx.com/docs/agent-sdk/interface/connectionEngine.md --- ### webSocket() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/webSocket.md ## AgentSocketsNotEnabledError --- ### fetch() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/fetch.md --- ### @rpc > Source: https://developers.telnyx.com/docs/agent-sdk/interface/rpc.md ## RpcOptions --- ### rpcSurface() > Source: https://developers.telnyx.com/docs/agent-sdk/interface/rpcSurface.md --- ### BYO Framework > Source: https://developers.telnyx.com/docs/agent-sdk/examples/bring-your-own-framework.md Any turn taking runs on the `Agent` class, whether a framework or a loop the user writes. Glue code joins the two. The class keeps the conversation, and the turn taking produces each reply. ## Write the Glue ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; export class Conversation extends Agent { async receive(text: string): Promise { await this.messages.add("user", text); await this.queue("process"); } async process(): Promise { const history = await this.messages.toOpenAI(); const reply = await takeTurn(history); await this.messages.add("assistant", reply); } } ``` - `receive` records the message in the [log](/docs/agent-sdk/interface/messages) and returns, inside the 30-second budget of an inbound call. - [`queue`](/docs/agent-sdk/interface/queue) runs `process` as a task, which has minutes, retries on failure and survives restarts. - `process` reads the history in the shape the turn taking expects and records the reply, so the next turn sees it. `takeTurn` is the slot. The log reads the history out in three shapes for it, `toOpenAI()`, `toAnthropic()` and `toLangChain()`. Under the entry `deploy` generates, a text or an email reaches the class's `receiveVia(text, from, key, via)`, so a class wired to channels implements that method, and `receive` is the RPC door. A client reaches it once the method is marked with [`@rpc()`](/docs/agent-sdk/interface/rpc) and [`authorize`](/docs/agent-sdk/interface/authorize) grants the client the `rpc` claim. ## Write the Loop by Hand The smallest turn taking is one model call. The Telnyx inference endpoint is reached through the `TELNYX` binding on [`env`](/docs/agent-sdk/interface/env) with the account's credential, so the loop holds no key. ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; import type Telnyx from "telnyx"; type ChatResponse = { choices: Array<{ message: { content: string } }> }; export class Conversation extends Agent { // receive() as above async process(): Promise { const history = await this.messages.toOpenAI(); const res = (await this.env.TELNYX.ai.openai.chat.createCompletion({ model: "zai-org/GLM-5.3-Flash", messages: [{ role: "system", content: "Answer in one or two sentences." }, ...history] as never, })) as ChatResponse; await this.messages.add("assistant", res.choices[0].message.content); } } ``` `Env` types no bindings, so the class adds `TELNYX`, and the history and the response are cast, as `managed/model.ts` does. A loop with tools calls the model again after each tool result. It records the call and the result with [`append()`](/docs/agent-sdk/interface/messages#append), and `toOpenAI()` returns them to the model on the next read. ## Plug In a Framework A framework takes the same place. LangGraph reads the `toLangChain()` history as it is. ```bash npm install @langchain/openai @langchain/langgraph @langchain/core zod ``` ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; import { ChatOpenAI } from "@langchain/openai"; import { createReactAgent } from "@langchain/langgraph/prebuilt"; import { tool } from "@langchain/core/tools"; import { z } from "zod"; const lookupOrder = tool( async ({ orderId }) => JSON.stringify({ orderId, status: "shipped" }), { name: "lookup_order", description: "Look up an order by its id.", schema: z.object({ orderId: z.string() }), }, ); const graph = createReactAgent({ llm: new ChatOpenAI({ model: "zai-org/GLM-5.3-Flash", apiKey: process.env.TELNYX_API_KEY, configuration: { baseURL: "https://api.telnyx.com/v2/ai/openai" }, }), tools: [lookupOrder], }); export class Conversation extends Agent { // receive() as above async process(): Promise { const history = await this.messages.toLangChain(); const out = await graph.invoke({ messages: [{ role: "system", content: "Answer in one or two sentences." }, ...history], }); await this.messages.add("assistant", String(out.messages.at(-1)?.content ?? "")); } } ``` - A framework makes its own HTTP calls, so it authenticates like any client. Its key reaches the class as an environment variable. - Only the final reply reaches the log. The tool calls inside the run stay with the framework, and `append()` records them when a later turn needs them. [The Agent Harness SDK](/docs/agent-sdk/harness-sdk) is Telnyx's own turn taking, and it takes the same place. [`createHarness()`](/docs/agent-sdk/harness-sdk/create-harness) builds it inside the class. --- ### Entry Points > Source: https://developers.telnyx.com/docs/agent-sdk/contract/entry-points.md The platform invokes the class at a few known points, and the class returns within a budget on each. The `Agent` class extends Edge Compute's [`StatefulActor`](/docs/edge-compute/stateful-actors/api-reference/base), and the platform calls it through the actor's entries. | Entry point | Invoked by | Contract | |---|---|---| | [`fetch(req)`](/docs/edge-compute/stateful-actors/guides/project-structure#two-exports) on the function | Every request to the address | Answered by `mountAgents`, which resolves the instance and picks the transport. [The Address and Transports](/docs/agent-sdk/contract/address-and-transports) has the three. | | Any method marked `@rpc` | `POST …/rpc/` on the conversation's address, and the socket's RPC frames | One call, JSON in and out, within the [30-second budget](/docs/edge-compute/stateful-actors/api-reference/errors). Work that needs longer goes to a queued task. | | A public method | A call through an [`ActorStub`](/docs/edge-compute/stateful-actors/api-reference/stub), from the function or from another instance | Actor RPC, under the [dispatch rules](/docs/edge-compute/stateful-actors/api-reference/base#dispatch-rules) of `StatefulActor`. `@rpc` does not apply to it. | | [`webSocket(ws, req)`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) | A WebSocket upgrade on the conversation's address | The class owns the socket. The default runs the agent socket protocol, and the `voice()` mixin takes a call's media stream. The mixin is the `@telnyx/edge-runtime/voice` export of [The Agent Runtime SDK](/docs/agent-sdk/runtime-sdk). | | `onTask(name, payload, ctx)` | The task scheduler, when a due task names no method on the class | Delivered at least once, inside the [alarm handler](/docs/edge-compute/stateful-actors/alarms), with a budget on the order of minutes. A task that names a method on the class is delivered to that method. [`queue()`](/docs/agent-sdk/interface/queue) creates a task. | | `authorize(token, req)` | Every connection, once | Resolve the credential into claims. [`authorize`](/docs/agent-sdk/interface/authorize) is the reference, and [Mounting Agents](/docs/agent-sdk/mounting-agents#authorization-composes-—-it-does-not-replace) has both gates. | | `onConnect(conn)`, `onAttach(att)` | A connection, as it is established and as it is admitted | Hooks. | | [`alarm(info)`](/docs/edge-compute/stateful-actors/api-reference/base#alarm-alarminfo) | The platform's alarm | Reserved by the SDK, which drives the task scheduler with it. | One instance runs one of these [at a time](/docs/edge-compute/stateful-actors/concepts/execution-model), so a handler never interleaves with another on the same conversation. [Execution Model](/docs/agents/model/execution-model) has the rest of the rules. A webhook is a request to `fetch` like any other, and what the function does with it is the function's own code. ## Activation The platform constructs the class on every activation. The constructor opens the instance's stores and re-arms the task scheduler before the instance takes a call. ```ts // agent/agent.ts constructor(ctx, env, options = {}) { super(ctx, env); // … this._tasks = new TaskScheduler(ctx.storage, () => randomUUID()); this._state = new StateStore(ctx.storage, () => this.initialState()); ctx.blockConcurrencyWhile(async () => { await beginActivation(ctx.storage); await this._tasks.rearm(this.now()); }); } ``` - [`StatefulActor`](/docs/edge-compute/stateful-actors/api-reference/base#construction) receives `ctx` and `env` through `super(ctx, env)`. It keeps them as `this.ctx` and `this.env`. - [`ctx.storage`](/docs/edge-compute/stateful-actors/api-reference/storage) backs the task scheduler and the state store. The message log and the event log are built on it too. - [`ctx.blockConcurrencyWhile`](/docs/edge-compute/stateful-actors/api-reference/context#ctx-blockconcurrencywhile-fn) runs the store setup and the re-arm. Every other call waits until both finish. The callback has a 30-second budget. ## The Fetch Entry The class does not override the actor's `fetch`. It inherits the default. ```ts // stateful-actor.ts async fetch(_req) { return new Response("Not Found", { status: 404 }); } ``` - [`fetch(req)`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req) receives every request to the instance that is not an upgrade. A class that serves the streams and RPC over HTTP overrides it and passes the request to an [`AgentHttpServer`](/docs/agent-sdk/internals/the-http-server). ## The WebSocket Entry The class overrides the actor's `webSocket` and hands each socket to its [socket server](/docs/agent-sdk/internals/the-socket-server). ```ts // agent/agent.ts webSocket(ws, req) { if (!this._overridesSeam("authorize") && !this._overridesSeam("onAttach") && !this._overridesSeam("webSocket")) { throw new AgentSocketsNotEnabledError(); } return this._socketServer().attach(ws, req); } ``` - [`webSocket(ws, req)`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) receives the accepted socket and the handshake request. A class that overrides none of the three seams throws before it touches the socket, so the socket is refused. ## The Alarm Entry The instance has one alarm. The task scheduler sets it through `ctx.storage`, to the earliest due task. ```ts // agent/tasks.ts async rearm(_now) { const due = await taskEarliestDue(this.storage); if (due === undefined) { await this.storage.deleteAlarm(); return; } await this.storage.setAlarm(due); } ``` - [`ctx.storage.setAlarm`](/docs/edge-compute/stateful-actors/alarms) receives the earliest due time, in milliseconds since the epoch. Setting it again replaces the previous time, so every task shares the one alarm. - [`ctx.storage.deleteAlarm`](/docs/edge-compute/stateful-actors/alarms) clears the alarm when no task is pending. When the alarm fires, the class's `alarm` drains every due task and re-arms. ```ts // agent/agent.ts async alarm(_info) { const dispatch = (task) => this._dispatch(task); // … for (;;) { const now = this.now(); const earliest = await taskEarliestDue(this.ctx.storage); if (earliest === undefined || earliest > now) break; // … await this._tasks.runDue(now, dispatch); } // … await this._tasks.rearm(this.now()); } ``` - [`alarm(info)`](/docs/edge-compute/stateful-actors/api-reference/base#alarm-alarminfo) is the entry the platform calls when the alarm fires. Every task the drain dispatches runs inside it, under the alarm's [time budget](/docs/edge-compute/stateful-actors/alarms#limits). --- ### The Address and Transports > Source: https://developers.telnyx.com/docs/agent-sdk/contract/address-and-transports.md Every conversation of a deployed agent is reachable at one address: ```text https://-.telnyxcompute.com/agents// ``` The host is the Edge Compute function's [public URL](/docs/edge-compute/configuration/routing#public-url-pattern). The path is the mount's. The shape of the request selects the transport, not the path: | The client sends | It gets | Use | |---|---|---| | `Upgrade: websocket` | The agent socket protocol: state and message sync, cursor-based resume | Clients, and the voice media stream | | `GET …?subscribe=state` | Server-Sent Events | State and message streams in a browser | | `POST …/rpc/` | One RPC call, JSON in and out | Any HTTP client | The upgrade reaches the instance's [`webSocket(ws, req)`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) entry. The `GET` and the `POST` reach its [`fetch(req)`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req) entry. The [AgentClient](/docs/agent-sdk/client-sdk/constructor) wraps the socket, and any HTTP or WebSocket client can speak the wire. The mount routes and adds no policy of its own. Two gates decide who may call. The mount's `authorize` runs at the edge, and the agent's [`authorize`](/docs/agent-sdk/interface/authorize) runs inside the instance. [Mounting Agents](/docs/agent-sdk/mounting-agents) is the reference, and its [authorization section](/docs/agent-sdk/mounting-agents#authorization-composes-—-it-does-not-replace) covers both gates. On a deployed function, Server-Sent Events arrive in batches about once a second rather than live. The WebSocket carries the same frames on the same address and is the live path. [AgentHttpServer](/docs/agent-sdk/internals/the-http-server) has the detail. --- ### Mounting Agents > Source: https://developers.telnyx.com/docs/agent-sdk/mounting-agents.md An agent is only reachable through an Edge Compute [function](/docs/edge-compute/stateful-actors/guides/project-structure#two-exports). Before `mountAgents`, every project wrote the function's front door by hand, and each copy differed a little. - It parsed the URL and checked for an upgrade. - It pulled the credential and encoded the name. - It picked the binding and called [`idFromName(...).fetch(req)`](/docs/edge-compute/stateful-actors/api-reference/namespace#idfromname-name-options). - It answered health checks. `mountAgents` *(SDK ≥ 0.12.0)* is that front door, already written. The user supplies the routing table and the policy, and the mount supplies the rest. ```ts import { mountAgents } from "@telnyx/edge-runtime/mount"; import type { ActorNamespace } from "@telnyx/edge-runtime"; interface Env { CONVERSATION: ActorNamespace; BILLING: ActorNamespace; } export default { fetch: mountAgents((env) => ({ conversation: env.CONVERSATION, billing: env.BILLING, })), }; ``` **`fetch:` is not optional.** `mountAgents` returns a handler, and a function entry must default-export an **object** carrying that handler on `fetch`. Writing `export default mountAgents(map)` produces a bundle the runtime refuses at load time — the deploy does not start, so there is no request to debug. The map is the entire routing table. Nothing is discovered, and no name is derived from a class name: an agent is reachable once it is written there, and an unknown mount key is a `404` with no binding consulted. It is a function of `env`, so bindings resolve per request and nothing is cached between them. Each value is an actor binding, an [`ActorNamespace`](/docs/edge-compute/stateful-actors/api-reference/namespace). An `[[actors]]` block in `telnyx.toml` declares it, as the Stateful Actors [configuration reference](/docs/edge-compute/stateful-actors/api-reference/configuration) shows. ## One Address, Three Transports Each mounted agent answers on `//`: - `` is the path prefix the mount owns, `/agents` unless the option sets another, [`base`](/docs/agent-sdk/internals/mount/mountAgents#mountoptions). - `` is a key of the map above. - `` is the routing name of one instance — one agent, one persistent identity. So the function above serves `/agents/conversation/alice` and `/agents/billing/acct-1004`. Each name reaches one [actor instance](/docs/edge-compute/stateful-actors/concepts/addressing), the same one on every request. The first request brings it up, as [Lifecycle & Placement](/docs/edge-compute/stateful-actors/concepts/lifecycle#where-it-runs) describes. **The shape of the request selects the transport, not the path.** The same address answers all three: | The client sends | Address | It gets | |---|---|---| | `Upgrade: websocket` | `/agents/conversation/alice` | the agent socket protocol | | `GET` | `/agents/conversation/alice?subscribe=state` | Server-Sent Events | | `POST` | `/agents/conversation/alice/rpc/humanReply` | one RPC call | This is why the [AgentClient](/docs/agent-sdk/client-sdk/constructor) reference connects to `wss://my-func.telnyxcompute.com/agents/conversation/alice` — that URL is the default `base`, the `conversation` mount key, and the name `alice`. A browser talking to the function above needs no route of its own: ```ts import { AgentClient } from "@telnyx/edge-runtime/client"; const agent = new AgentClient( "wss://my-func.telnyxcompute.com/agents/conversation/alice", { token: sessionToken, subscribe: ["state", "messages"], resume: true }, ); agent.onState(render); await agent.stub.humanReply("On it."); ``` An RPC call from a page with no SDK at all is the same address with a method on the end: ```bash curl -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '["On it."]' \ https://my-func.telnyxcompute.com/agents/conversation/alice/rpc/humanReply ``` The request body is the argument list, and the response is the same `result` / `error` frame a WebSocket caller would receive. Only methods decorated with [`@rpc()`](/docs/agent-sdk/interface/rpc) are callable. **SSE arrives in batches on deployed functions.** A streamed response cannot cross the actor boundary, so each SSE response carries the frames ready when the agent answers. The `EventSource` reconnects about once a second and resumes from `Last-Event-ID`. The WebSocket and RPC paths are unaffected, and SSE streams live in local development. The WebSocket path is the live one for production. It carries the same frames under the same policy on the same address, so the change is `new WebSocket(url)` in place of `new EventSource(url)`, or `AgentClient`, which reconnects and resumes on its own. The full detail is on the [AgentHttpServer](/docs/agent-sdk/internals/the-http-server) page. ## Authorization Composes — It Does Not Replace The mount adds **no policy of its own**. It routes, and it runs the one `authorize` callback it is given. That callback does not stand in for the agent's own `authorize(token, req)`: both run, and they do different jobs. **Gate one, at the edge.** `authorize(req, route)` runs after the address resolves and **before anything touches an actor**, on every transport — an upgrade, an SSE stream, and each RPC POST alike. It receives the request unmodified and the resolved [route](/docs/agent-sdk/internals/mount/mountAgents#mountroute): the mount key, the decoded name, the actor id, the transport, and the method for an RPC. Answer with a `Response` to reject (nothing is forwarded, no actor wakes), with headers to admit and stamp, or with nothing to admit as-is. **Gate two, inside the agent.** The caller's credential rides through **untouched** — `?token=` or an `Authorization` header, exactly as sent. The agent's [`authorize`](/docs/agent-sdk/interface/authorize) resolves this connection's [claims](/docs/agent-sdk/interface/authorize#claim) from it exactly as it would with no mount in front, and [`onAttach`](/docs/agent-sdk/interface/onAttach) may still veto. ```ts // The function: who is this, and may they address this agent at all? export default { fetch: mountAgents((env) => ({ conversation: env.CONVERSATION }), { authorize: async (req, { name }) => { const user = await verify(req.headers.get("authorization")); if (!user) return new Response("unauthorized", { status: 401 }); if (user.deskId !== name) return new Response("forbidden", { status: 403 }); return { "x-desk-user": user.id, "x-desk-role": user.role }; }, }), }; ``` ```ts // The agent: given the credential, what may this connection DO? import { Agent, type Claim } from "@telnyx/edge-runtime"; export class Conversation extends Agent { protected override authorize(token: string | undefined): readonly Claim[] { if (token === undefined) return ["read"]; // anonymous watcher return isOperator(token) ? ["read", "rpc"] : ["read"]; } } ``` Identity at the mount, grants in the agent. Two rules make the stamped identity safe to trust: - **A stamped header overwrites** any header of the same name the caller sent, so a client cannot forge an identity the agent trusts. - **Headers the mount does not stamp are forwarded as the caller sent them.** The agent trusts only what the mount stamps. A throw from the mount's `authorize` is not an admission — it propagates and the request never reaches an actor. Reading the body is safe: the agent is handed an independent copy, so a signature verified here still arrives there intact. That copy is made only for a request that carries a body, and it does buffer while both copies are outstanding — on a large streamed upload, prefer deciding from the headers. ## Names Customers Already Use Actor ids are not free-form: only ASCII letters, digits, `-`, `_`, and `.` are addressable, and an id built from anything else belongs to an instance that never activates. The names an application routes on are not so confined — a phone number, an email address, a composite key, a name with accents or emoji. The mount decodes the name segment and re-encodes it with [`encodeAgentName`](/docs/agent-sdk/internals/mount/encodeAgentName), which maps any name onto the addressable set reversibly: ```ts import { encodeAgentName, decodeAgentName } from "@telnyx/edge-runtime/mount"; encodeAgentName("alice"); // "alice" — already addressable, unchanged encodeAgentName("+15550100"); // ":2b:15550100" encodeAgentName("user@ex.com"); // "user:40:ex.com" decodeAgentName(":2b:15550100"); // "+15550100" — render an id back for a human ``` `/agents/conversation/%2B15550100` therefore addresses the agent for `+15550100`, and no two names ever share an instance. Three things to keep in mind: - **The mapping is part of an actor's identity and is frozen.** The id a name first resolves to is where that instance's state and timers live. Do not re-derive the rule by hand — call `encodeAgentName` from any other front door that addresses the same instances, or that door points the name at a different, empty instance. - **Case is significant.** `alice` and `Alice` are two agents. Names meant to reach one agent are lowercased before routing. - **Encode the raw name exactly once.** Encoding an already-encoded name escapes its `:` signs and addresses something else. ### How Long a Name May Be The limit is on the actor id **once URL-escaped** — `MAX_ESCAPED_ACTOR_ID_LENGTH`, **225** characters — because the id is carried into the name of the file the instance's persistent state is kept in, which is capped at 255 bytes. How many characters of *name* that allows depends on which characters they are, since an escape is longer than what it replaces: | A name of… | costs per character | one run fits | |---|---|---| | ASCII letters, digits, `-`, `_`, `.` | 1 | 225 | | accented Latin, Greek, Cyrillic (2 bytes) | 4 | 54 | | most CJK and symbols such as `☕` (3 bytes) | 6 | 36 | | emoji and other astral characters (4 bytes) | 8 | 27 | Every separate escaped run also spends 6 on the pair of `:` bracketing it, so a mixed name fits less than any single row suggests. A name whose id would exceed the ceiling is refused by the mount with `400 malformed_name` before any actor wakes, and `encodeAgentName` throws rather than handing back an unusable id. **An over-long id does not fail on first use.** The instance activates, serves requests, and accepts writes; the long name is only needed when it is loaded again after being evicted from memory, and from then on the instance cannot be opened and what it stored is unreachable. Nothing about the first, healthy run of it looks wrong — which is why the limit is checked up front. See [Limits](/docs/agent-sdk/limits#max_escaped_actor_id_length) and [`escapedActorIdLength()`](/docs/agent-sdk/limits#escapedactoridlength). ## What the Mount Answers Itself | Request | Answer | |---|---| | `/health/liveness`, `/health/readiness` | `200 ok`, no actor woken, nothing about what is mounted in the body | | A path outside `base` | the [`fallback`](/docs/agent-sdk/internals/mount/mountAgents#mountoptions), or `404` | | Unknown mount key, malformed address, empty name | `404` — one body for all of them | | A name with no faithful actor id | `400`, naming the problem | | A shape matching no transport — a `PUT`, a `GET` on an RPC address, an upgrade to one | `405` with an `Allow` header | No actor is woken for any of them. Refusals from the mount carry a JSON body with an `error` of `not_found`, `method_not_allowed`, or `malformed_name`; answers from the agent — including its own errors — are relayed unchanged. Set `health: false` when the surrounding function owns its own health routes. ## Composing with Other Routes A mount does not have to own the whole function. `fallback` receives every request whose path is not under `base`, so the function's own handler keeps its routes and the agent addresses never reach it: ```ts export default { fetch: mountAgents((env) => ({ conversation: env.CONVERSATION }), { base: "/agents", // the paths the mount owns fallback: myRouter.fetch, // every other path health: false, // the function answers its own health checks }), }; ``` ## Cross-origin Browsers Absent `cors`, the mount sends no CORS headers and answers `OPTIONS` with `405`, so a page from another origin cannot reach it. Opt in when a browser page served elsewhere must open an `EventSource` or `fetch` an RPC address: ```ts { cors: { origin: ["https://desk.example.com"], credentials: true, // requires a concrete origin — never "*" }, } ``` It is a passthrough and nothing more: it does not authenticate, and it never substitutes for `authorize`. Mount names are ordinary path segments, not secrets — they are part of the address every legitimate client already knows. ## Next - [`mountAgents` reference](/docs/agent-sdk/internals/the-mount) — every option, type, and refusal in full - [AgentClient](/docs/agent-sdk/client-sdk/constructor) — the browser/Node client that connects to the address above - [AgentSocketServer](/docs/agent-sdk/internals/the-socket-server) and [AgentHttpServer](/docs/agent-sdk/internals/the-http-server) — what answers on the agent side of each transport - [`webSocket()`](/docs/agent-sdk/interface/webSocket) — the entry a class overrides to own its sockets --- ### The Mount > Source: https://developers.telnyx.com/docs/agent-sdk/internals/the-mount.md `mountAgents` *(SDK ≥ 0.12.0)* is the front door for an Edge Compute [function](/docs/edge-compute/stateful-actors/guides/project-structure#two-exports) that serves agents. One call replaces the routing file a function would otherwise write by hand. The function keeps only its own policy. It ships at `@telnyx/edge-runtime/mount`. ```ts import { mountAgents } from "@telnyx/edge-runtime/mount"; import type { ActorNamespace } from "@telnyx/edge-runtime"; interface Env { CONVERSATION: ActorNamespace; } export default { fetch: mountAgents((env) => ({ conversation: env.CONVERSATION })), }; ``` **The entry must export an object carrying `fetch`, not the handler itself.** `mountAgents` returns a `fetch` handler, so it goes on the `fetch` property of the module's default export. A bare-function default export — `export default mountAgents(map)` — is refused by the function runtime at load time, and the failure is a bundle that never starts rather than a request that 500s. ## The Address, and What Selects the Transport Every mounted agent answers on the same shape, `//`, where `` is a key of the map and `` is the routing name of one instance. The **request** picks the transport; the path never changes: | Request | Address | Serves | |---|---|---| | `Upgrade: websocket` | `//` | the agent socket protocol | | `GET` | `//?subscribe=state` | Server-Sent Events | | `POST` | `///rpc/` | one RPC call | `base` defaults to `/agents`, so the map above serves `/agents/conversation/alice` on all three. **That is the URL the [AgentClient](/docs/agent-sdk/client-sdk/constructor) examples connect to** — `wss://my-func.telnyxcompute.com/agents/conversation/alice` is this default `base`, this mount key, and this name: ```ts import { AgentClient } from "@telnyx/edge-runtime/client"; // mount key ─────────────────────────┐ ┌─── routing name const agent = new AgentClient( "wss://my-func.telnyxcompute.com/agents/conversation/alice", ); ``` A hand-written front door can serve any shape it likes; `mountAgents` is what makes *this* shape route. The upgrade is handed to the agent's [`webSocket`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req); `GET` and `POST` are handed to the agent's [`fetch`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req), where an [AgentHttpServer](/docs/agent-sdk/internals/the-http-server) over the agent's connection engine answers them once the class routes `fetch` there. The forwarded request keeps its URL and query string, so `subscribe`, `Last-Event-ID` resume, and the `/rpc/` segment all arrive as the caller wrote them. **SSE arrives in batches on deployed functions.** Each SSE response carries the frames ready when the agent answers, and the `EventSource` reconnects about once a second. The WebSocket and RPC paths are unaffected, and SSE streams live in local development. [AgentHttpServer](/docs/agent-sdk/internals/the-http-server) has the detail. The WebSocket path is the live one for production, on the same address under the same policy. ## The Hand-Off The handler the mount returns resolves the binding, then hands the request to the instance. ```ts // mount.ts return async function handleAgentRequest(req, env) { // … const table = map(env); const namespace = table !== null && typeof table === "object" && ownKey(table, mount) ? table[mount] : undefined; if (namespace === undefined || typeof namespace.idFromName !== "function") { return withCors(notFound(), cors, req); } // … const stub = namespace.idFromName(actorId); return withCors(await stub.fetch(new Request(forwardable, { headers })), cors, req); }; ``` - [`fetch`](/docs/edge-compute/stateful-actors/guides/project-structure#two-exports) on the function's default export is the entry this handler fills. The platform calls it with each request and the function's `env`. - [`ActorNamespace`](/docs/edge-compute/stateful-actors/api-reference/namespace) is what each map value must be. `map(env)` reads the bindings on every request. The mount answers `404` for a value without `idFromName`. - [`idFromName`](/docs/edge-compute/stateful-actors/api-reference/namespace#idfromname-name-options) receives the actor id that `encodeAgentName` built. The same id always reaches the same instance, as [Addressing](/docs/edge-compute/stateful-actors/concepts/addressing) describes. - [`ActorStub.fetch`](/docs/edge-compute/stateful-actors/api-reference/stub) receives the request with its URL unchanged and the stamped headers. An upgrade reaches the instance's [`webSocket`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) entry, and any other request reaches its [`fetch`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req) entry. ## Two Gates, Not One The mount's [`authorize`](/docs/agent-sdk/internals/mount/mountAgents#mountoptions) does not replace the agent's own `authorize(token, req)`. It **composes with** it, and both run: 1. **At the edge, before any actor wakes** — `authorize(req, route)` sees the inbound request and what the mount resolved from it (`mount`, `name`, `actorId`, `transport`, and for RPC the `method`). Return a `Response` to reject — nothing is forwarded and no actor is woken — or return headers to stamp identity onto the request, or nothing to admit as-is. It runs identically on all three transports, so no request shape reaches an agent around it. 2. **Inside the agent** — the caller's credential rides through untouched (`?token=`, or an `Authorization` header), so [`Agent.authorize`](/docs/agent-sdk/interface/authorize) resolves this connection's [claims](/docs/agent-sdk/interface/authorize#claim) from it exactly as it would unmounted, and `onAttach` may still veto. Stamp identity at the mount; decide grants in the agent. ```ts export default { fetch: mountAgents((env) => ({ conversation: env.CONVERSATION }), { authorize: async (req, { mount, name }) => { const user = await verify(req.headers.get("authorization")); if (!user) return new Response("unauthorized", { status: 401 }); if (user.id !== name) return new Response("forbidden", { status: 403 }); return { "x-desk-user": user.id }; // stamped — overwrites any caller header }, }), }; ``` A stamped header always wins: it overwrites a header of the same name the caller sent, so a client cannot forge an identity the agent trusts. Headers the mount does **not** stamp are forwarded as the caller sent them, so the agent trusts only what the mount stamps. The [Mounting Agents](/docs/agent-sdk/mounting-agents) guide walks the whole path, including composing the mount with other routes and the cross-origin opt-in. ## Names A routing name is what a caller writes in the address; an **actor id** is what the platform files an instance's state and timers under, and only ASCII letters, digits, `-`, `_`, and `.` are addressable. `mountAgents` runs every name it resolves through `encodeAgentName`, so natural names — a phone number, an email address, a composite key, a name with accents or emoji — reach a persistent instance without the caller thinking about encoding. Any front door written by hand that must address the same instances calls the same function. Re-deriving the rule points a name at a different, empty instance. The instance reads its actor id as [`ctx.id`](/docs/edge-compute/stateful-actors/api-reference/context#ctx-id). The ceiling is on the id **once URL-escaped**, not on the name — see [MAX_ESCAPED_ACTOR_ID_LENGTH](/docs/agent-sdk/limits#max_escaped_actor_id_length) on the Limits page for what each kind of character costs (225 ASCII, 54 two-byte, 36 three-byte, 27 emoji, plus 6 per escaped run) and why an over-long id fails only after an eviction rather than on first use. --- ### mountAgents() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/mount/mountAgents.md ## AgentMountMap ## MountOptions ## MountRoute ## MountTransport ## MountCorsOptions ## MountAuthorizeResult ## MountHeadersInit --- ### encodeAgentName() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/mount/encodeAgentName.md --- ### decodeAgentName() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/mount/decodeAgentName.md --- ### The Socket Server > Source: https://developers.telnyx.com/docs/agent-sdk/internals/the-socket-server.md `AgentSocketServer` is the server half of the agent socket protocol — it drives every [WebSocket](/docs/edge-compute/stateful-actors/websockets) an agent holds. Construct one per actor instance and delegate the actor's [`webSocket(ws, req)`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) to `attach()`. The server sends each admitted connection a state snapshot followed by `hello`, dispatches inbound RPC frames to the actor's [`@rpc()`](/docs/agent-sdk/interface/rpc)-decorated methods, and pushes incremental updates through the `broadcast*` methods as the agent's data changes. ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; import type { MergePatch } from "@telnyx/edge-runtime/internal"; import { AgentSocketServer, type AgentServerSocket } from "@telnyx/edge-runtime/agent-socket"; interface ConvState extends Record { status: string; } export class Conversation extends Agent { private desk = new AgentSocketServer(this, { getState: () => this.getState(), getMessages: () => this.messages.all(), // token → claims; throw to reject; `undefined` = anonymous client authorize: (token) => (token === undefined ? ["read"] : ["read", "rpc"]), }); async webSocket(ws: AgentServerSocket, req: Request): Promise { await this.desk.attach(ws, req); } protected override async setState(patch: MergePatch): Promise { const next = await super.setState(patch); this.desk.broadcastPatch(patch); // incremental push to every client return next; } } ``` With an `authorize` hook configured, every connection becomes an authorized session: a client that opens with an `attach` frame presents its token, `authorize(token)` maps it to claims, and per-stream subscriptions are negotiated; a client that never attaches is authorized as anonymous — `authorize(undefined)` — so admit it with limited claims, or throw to reject. RPC `call` frames require the `"rpc"` claim, which is what lets read-only watchers and fully privileged operators share one socket endpoint. ## Attaching a Socket `attach()` registers its listeners on the actor's socket before its first `await`. ```ts // agent-client/server.ts ws.on("close", gone); ws.on("error", gone); ws.on("message", (data, isBinary) => { if (admitted) { return ordered ? enqueue(data, isBinary) : this.handleMessage(ws, data, isBinary, req); } // … if (buffered.length >= MAX_PENDING_INBOUND) { this.sendError(ws, "protocol_error", "too many frames before connect"); this.reject(ws, 1013, "inbound queue overflow"); return; } buffered.push({ data, isBinary }); // … }); ``` - [`webSocket(ws, req)`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) hands `attach()` the accepted socket and the handshake request. The listeners go on before the entry returns, as the entry requires. - [`ws.on("message")`](/docs/edge-compute/stateful-actors/websockets#messages-are-single-threaded-like-everything-else) delivers each frame as one turn of the instance, serialized with its calls and its alarm. Each turn runs under the 30-second method budget. - [`ws.close(1013)`](/docs/edge-compute/stateful-actors/websockets/lifecycle#how-connections-end) ends a connection that sends more than 64 frames, the value of `MAX_PENDING_INBOUND`, before it is admitted. The platform uses the same code when its own event queue overflows. ## Broadcasts Every `broadcast*` method ends in the same loop over the sockets the server admitted. ```ts // agent-client/server.ts broadcastTo(frame, deliver) { const text = encodeFrame(frame); for (const ws of [...this.sockets]) { if (!deliver(this.sessions.get(ws))) continue; if (ws.readyState !== ws.OPEN) continue; try { ws.send(text); } catch { this.sockets.delete(ws); this.sessions.delete(ws); } } } ``` - [`ws.send`](/docs/edge-compute/stateful-actors/websockets#messages-are-single-threaded-like-everything-else) goes to each admitted socket subscribed to the frame's stream. The send is immediate, and it is not held until the turn's writes commit. - [`ctx.broadcast()`](/docs/edge-compute/stateful-actors/api-reference/context#ctx-broadcast-data) and [`ctx.count()`](/docs/edge-compute/stateful-actors/api-reference/context#ctx-count) are not used. Both cover every socket on the instance. The server keeps its own set instead, as [Sending to Some Sockets, Not All](/docs/edge-compute/stateful-actors/websockets#sending-to-some-sockets-not-all) describes. ## AgentSocketServerOptions ## AgentConnectContext --- ### new AgentSocketServer() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/constructor.md > **new AgentSocketServer**\<`TState`\>(`actor`: `object`, `opts`: [`AgentSocketServerOptions`](/docs/agent-sdk/internals/the-socket-server#agentsocketserveroptions)\<`TState`\>): `AgentSocketServer`\<`TState`\> Creates the socket server for one actor instance. Construct one per instance, usually as a field of the class, and delegate the class's `webSocket(ws, req)` to [`attach`](/docs/agent-sdk/internals/socket/attach). ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; import { AgentSocketServer, type AgentServerSocket } from "@telnyx/edge-runtime/agent-socket"; interface ConvState extends Record { status: string; } export class Conversation extends Agent { private desk = new AgentSocketServer(this, { getState: () => this.getState(), getMessages: () => this.messages.all(), authorize: (token) => (token === undefined ? ["read"] : ["read", "rpc"]), }); async webSocket(ws: AgentServerSocket, req: Request): Promise { await this.desk.attach(ws, req); } } ``` **Parameters** | Parameter | Type | Meaning | |---|---|---| | `actor` | `object` | The instance whose `@rpc()` methods inbound `call` frames dispatch to, usually `this`. | | `opts` | [`AgentSocketServerOptions`](/docs/agent-sdk/internals/the-socket-server#agentsocketserveroptions)\<`TState`\> | How the server reads state and messages, and how it authorizes a connection. | **Type Parameters** | Parameter | Meaning | |---|---| | `TState` | The agent's persistent state shape, as snapshotted and broadcast to clients. | --- ### attach() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/attach.md ## The Actor Entry The actor's [`webSocket(ws, req)`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) entry calls `attach()` once per accepted connection. [The Socket Server](/docs/agent-sdk/internals/the-socket-server#attaching-a-socket) shows the listeners it registers. ## AgentServerSocket --- ### broadcastPatch() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/broadcastPatch.md --- ### broadcastSnapshot() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/broadcastSnapshot.md --- ### broadcastMessages() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/broadcastMessages.md --- ### broadcastEvent() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/broadcastEvent.md --- ### handleCall() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/handleCall.md ## HandleCallOptions ## HandleCallResult --- ### close() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/close.md ## Close Codes The default code `1001` is the code a client also receives when an actor restarts or moves. On it, a client reconnects promptly, as [Connection Lifecycle](/docs/edge-compute/stateful-actors/websockets/lifecycle#how-connections-end) describes. --- ### watcherCount > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/watcherCount.md --- ### authorizeEnabled > Source: https://developers.telnyx.com/docs/agent-sdk/internals/socket/authorizeEnabled.md --- ### The HTTP Server > Source: https://developers.telnyx.com/docs/agent-sdk/internals/the-http-server.md `AgentHttpServer` *(SDK ≥ 0.11.0)* is the HTTP front door for an [AgentSocketServer](/docs/agent-sdk/internals/the-socket-server): the agent's streams over Server-Sent Events (**GET** answers a `text/event-stream` response), and its RPC surface over **POST** to `…/rpc/`. It is a second encoder over the same server — same frames, same `authorize` / `onAttach` policy, same dispatch as the WebSocket path — so a plain page with an `EventSource` and `fetch()` needs no SDK at all. **SSE arrives in batches on deployed functions.** A streamed response cannot cross the actor boundary on the deployed platform. Each SSE response carries the frames available when the handler returns, waiting up to 200 ms for the first, and ends with `retry: 1000`. The `EventSource` then reconnects and resumes from `Last-Event-ID`, so a deployed agent's SSE behaves as a poll about once a second. The RPC path over POST is unaffected, and SSE streams live in local development. The WebSocket path is the live one for production. It carries the same frames under the same `authorize` and `onAttach` policy, and `mountAgents` serves it on the same address. The change is `new WebSocket(url)` in place of `new EventSource(url)`, or [AgentClient](/docs/agent-sdk/client-sdk/constructor), which reconnects and resumes on its own. Construct one over the socket server the actor's [`webSocket`](/docs/edge-compute/stateful-actors/api-reference/base#websocket-ws-req) delegates to, and route HTTP requests from the actor's [`fetch`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req) into [`fetch()`](/docs/agent-sdk/internals/http/fetch): ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; import { AgentSocketServer, type AgentServerSocket } from "@telnyx/edge-runtime/agent-socket"; import { AgentHttpServer } from "@telnyx/edge-runtime/agent-http"; export class Conversation extends Agent { private desk = new AgentSocketServer>(this, { getState: () => this.getState(), getMessages: () => this.messages.all(), authorize: (token) => (token === "secret" ? ["read", "rpc"] : ["read"]), }); private door = new AgentHttpServer(this.desk); async webSocket(ws: AgentServerSocket, req: Request): Promise { await this.desk.attach(ws, req); } override fetch(req: Request): Promise { return this.door.fetch(req); } } ``` On the SSE path the credential rides the `token` query parameter — an `EventSource` cannot set headers — and `subscribe` picks the streams (`subscribe=state,messages`; omitted = every stream the server offers). Each server frame becomes one SSE event, and the `id:` carries resume cursors so the browser's automatic reconnect replays only what it missed. On the RPC path the credential rides `Authorization: Bearer ` (preferred) or the same query parameter; the JSON-array request body is the argument list, and the response body is the same `result` / `error` frame a WebSocket caller would receive. `mountAgents` hands a mounted agent's `GET` and `POST` requests to the actor's `fetch` on `/agents//`. The override above answers them there, and the function needs no routing code of its own. See [`mountAgents`](/docs/agent-sdk/internals/the-mount). Two limits, by design: SSE is one-way, so there are no server→client calls mid-stream (RPC is client-initiated POST only), and there is no ping/pong — an `EventSource` detects a dropped stream and reconnects by itself. ## The Fetch Entry `AgentHttpServer.fetch` is the body of the actor's `fetch` entry. It chooses between the RPC and the stream by method and address. ```ts // agent-client/http.ts async fetch(req) { const url = new URL(req.url); const parsed = rpcMethodFromPath(url.pathname); if (parsed !== undefined) { // … if (req.method !== "POST") { return frameResponse(syntheticError("protocol_error", "RPC requires POST"), 405); } return this.handleRpc(req, parsed.method); } if (req.method === "GET") return this.handleSse(req); return frameResponse(syntheticError("protocol_error", `unsupported method ${req.method}`), 405); } ``` - [`fetch(req)`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req) on the actor passes the request the mount forwarded, with its URL and query string intact. `Agent` inherits the base `fetch`, which answers `404`. The example above overrides it. - [`ActorFetchTimeoutError`](/docs/edge-compute/stateful-actors/api-reference/errors) ends a `fetch` that runs past its 30-second budget. An RPC over `POST` runs inside that `fetch` and shares the budget. --- ### new AgentHttpServer() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/http/constructor.md > **new AgentHttpServer**\<`TState`\>(`server`: [`AgentSocketServer`](/docs/agent-sdk/internals/the-socket-server)\<`TState`\>): `AgentHttpServer`\<`TState`\> Creates the HTTP transport over an existing socket server. RPC over `POST …/rpc/` and the SSE streams use that server's authorization and dispatch, so one policy covers both transports. ```ts import { Agent, type Env } from "@telnyx/edge-runtime"; import { AgentSocketServer } from "@telnyx/edge-runtime/agent-socket"; import { AgentHttpServer } from "@telnyx/edge-runtime/agent-http"; export class Conversation extends Agent { private desk = new AgentSocketServer>(this, { getState: () => this.getState(), authorize: (token) => (token === undefined ? ["read"] : ["read", "rpc"]), }); private door = new AgentHttpServer(this.desk); override fetch(req: Request): Promise { return this.door.fetch(req); } } ``` **Parameters** | Parameter | Type | Meaning | |---|---|---| | `server` | [`AgentSocketServer`](/docs/agent-sdk/internals/the-socket-server)\<`TState`\> | The instance's socket server. | **Type Parameters** | Parameter | Default | Meaning | |---|---|---| | `TState` | `Record` | The agent's persistent state shape, as served by the socket server. | --- ### fetch() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/http/fetch.md ## The Actor Entry The actor's [`fetch(req)`](/docs/edge-compute/stateful-actors/api-reference/base#fetch-req) entry calls it, from an override on the class. [The HTTP Server](/docs/agent-sdk/internals/the-http-server#the-fetch-entry) shows the method. --- ### handleRpc() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/http/handleRpc.md --- ### handleSse() > Source: https://developers.telnyx.com/docs/agent-sdk/internals/http/handleSse.md --- ### The Protocol > Source: https://developers.telnyx.com/docs/agent-sdk/internals/protocol.md The socket server, the HTTP server and [`AgentClient`](/docs/agent-sdk/client-sdk) speak one protocol of JSON frames, encoded with SuperJSON so that a `Date`, a `Map`, a `Set` or `undefined` in a payload survives the wire. `@telnyx/edge-runtime/agent-socket` exports the frame functions and types for servers, and `@telnyx/edge-runtime/client` exports the same set for clients, with `isFrame` and `applyMergePatch` besides. ```ts import { encodeFrame, parseKnownFrame, type AnyKnownFrame } from "@telnyx/edge-runtime/agent-socket"; import { applyMergePatch, isFrame } from "@telnyx/edge-runtime/client"; ``` ## Versions | Constant | Value | Meaning | |---|---|---| | `PROTOCOL_V1` | `1` | The v1 wire, the version the server and the client speak today. | | `PROTOCOL_V2` | `2` | The v2 wire, the `attach`, `attached` and `event` vocabulary of attach-mode sessions. | | `PROTOCOL_VERSION` | `1` | The version that is safe to stamp on the wire today. It stays equal to `PROTOCOL_V1` until both sides emit v2 frames, and v2 frames are stamped with `PROTOCOL_V2`. | Every frame carries its version as `v` and its kind as `kind`. ## Functions | Function | Exported From | Does | |---|---|---| | `encodeFrame(frame: AnyKnownFrame): string` | both | Encodes a frame of either version to a SuperJSON text frame. | | `parseFrame(text: string): AnyFrame` | both | Parses a v1 text frame. Throws on malformed input. | | `parseKnownFrame(text: string): AnyKnownFrame` | both | Parses a text frame of either version. Throws on malformed input. | | `isKnownFrame(value: unknown): value is AnyKnownFrame` | both | `true` for a frame of either version. | | `isFrame(value: unknown): value is AnyFrame` | `./client` | `true` for a frame of the shipped v1 protocol. | | `applyMergePatch(target, patch): Record` | `./client` | Applies an RFC 7396 merge patch to `target` and returns it: `null` deletes a key, objects merge recursively, and anything else replaces. It is the same function the server's `setState` uses. | ## v1 Frames `AnyFrame` is the union of every v1 frame. | `kind` | Sent By | Fields | Meaning | |---|---|---|---| | `call` | Client | `id`, `method`, `args?` | Invoke an `@rpc()` method. The answer is a `result` or an `error` with the same `id`. | | `ping` | Client | None | A heartbeat, answered with `pong`. | | `hello` | Server | None | Ends the bootstrap: the link is usable, and buffered calls flush. | | `state` | Server | `snapshot?`, `patch?` | A `snapshot` replaces the client's state; a `patch` is a merge patch on top of it. A connect sends a snapshot, and each `setState` a patch. | | `messages` | Server | `snapshot?`, `appended?` | The full message log on connect, then the newly appended messages. | | `result` | Server | `id`, `value` | The return value of the `call` with that `id`. | | `error` | Server | `id?`, `code`, `message` | With an `id`, that call rejects. Without one, the error is connection-level and the client rebuilds the link. | | `pong` | Server | None | The answer to `ping`. | `ErrorCode` is `"method_not_found"`, `"method_private"`, `"method_error"`, `"protocol_error"` or `"version_mismatch"`. ## v2 Frames `AnyFrameV2` is the union of the attach-mode frames, `AnyKnownFrame` the union of both versions, and `FrameKindV2` the v2 `kind` values. Each v2 frame is exported as its own type. | Type | `kind` | Sent By | Fields | Meaning | |---|---|---|---|---| | `AttachFrame` | `attach` | Client | `token?`, `subscribe?`, `cursors?` | Opens or reopens a session. The token is the credential, `subscribe` the [`Stream`](#streams-and-claims)s wanted, and `cursors` the per-stream positions to resume after, `{ events: 41 }` for example. | | `AttachedFrame` | `attached` | Server | `grants`, `accepted` | The [`Claim`](#streams-and-claims)s the connection holds, and the accepted subset of the requested streams. | | `EventFrame` | `event` | Server | `seq`, `type`, `payload`, `at` | One item of the agent's persistent [event log](/docs/agent-sdk/interface/events), in strict `seq` order. `seq` is also the resume cursor. | | `ErrorFrameV2` | `error` | Server | `id?`, `code`, `message` | The v2 error, with an `ErrorCodeV2`. | `ErrorCodeV2` is any `ErrorCode`, `"unauthorized"` or `"subscription_denied"`. ## Streams and Claims `Stream` is `"state"`, `"messages"` or `"events"`, the streams a v2 client can subscribe to. `Claim` is `"read"`, `"rpc"` or any other string: a capability [`authorize`](/docs/agent-sdk/interface/authorize) grants a connection. With `authorize` configured, a `call` frame needs the `"rpc"` claim. --- ### Limits > Source: https://developers.telnyx.com/docs/agent-sdk/limits.md ## Execution budgets | Context | Budget | On overrun | |---|---|---| | Inbound RPC method (e.g. `receive()`) | 30s wall-clock (default) | Call fails with [`ActorMethodTimeoutError`](/docs/edge-compute/stateful-actors/api-reference/errors) | | Queued / scheduled task (runs in [`alarm()`](/docs/edge-compute/stateful-actors/api-reference/base#alarm-alarminfo)) | Larger — [on the order of minutes](/docs/edge-compute/stateful-actors/alarms#limits) | Run counts as failed; task retries | Do LLM and outbound API work in tasks, not inbound methods — see [Execution Model](/docs/agents/model/execution-model). Full platform numbers live in the [StatefulActor API reference](/docs/edge-compute/stateful-actors/api-reference/base). ## Task retries A task that throws retries up to its `maxRetries` (default **5**) with exponential backoff, then is parked — it stops retrying and no longer fires. `every()` tasks reset their attempt count after each successful run. The drain catches a task that throws, so the failure never leaves the alarm handler. ```ts // agent/tasks.ts for (const task of due) { // … let threw = false; try { await dispatch(task); } catch { threw = true; } ran += 1; if (threw) { await this.settleFailure(now, task, spokenFor(task.id)); continue; } // … } ``` - [`alarm(info)`](/docs/edge-compute/stateful-actors/api-reference/base#alarm-alarminfo) returns normally after a task fails. The SDK counts the attempt itself, and `info.retryCount` plays no part. - The alarm's own [redelivery](/docs/edge-compute/stateful-actors/alarms#delivery-contract) applies only when the handler itself fails, as on an overrun of its budget. That retry follows the platform's policy, not `maxRetries`. ## Storage Message history and state live in the actor's persistent storage and are subject to its size caps — see the [storage reference](/docs/edge-compute/stateful-actors/api-reference/storage). Message history is append-only — there is no delete or trim API. `last(n)` reads a bounded window, but writes accumulate forever. For relational or queryable data, use the instance's embedded SQL database instead, which the [SQL guide](/docs/edge-compute/stateful-actors/guides/storage/sql) covers. One database holds up to 1 GB, and one bound value up to 2 MiB. Since SDK 0.13.0 the message log, the state, the progress events and the scheduled tasks are kept in that same database, the one at `this.ctx.storage.sql`. The SDK owns every table whose name starts with `_a_`. Those tables count toward the database's 1 GB. Reads stay flat as a log grows. An instance that already has data migrates itself once, on its first write after the upgrade. The SDK creates the tables through `ctx.storage` when an instance activates. ```ts // agent/sql-backing.ts export function createSchema(storage) { const engine = storage.sql; const present = engine .exec(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ? LIMIT 1`, TASK_DUE_INDEX) .toArray(); if (present.length > 0) return; storage.transactionSync(() => engine.exec(SCHEMA)); } ``` - [`ctx.storage.sql`](/docs/edge-compute/stateful-actors/api-reference/storage#sql) is the engine the SDK's tables are created in. It is the instance's one SQL database. - [`ctx.storage.transactionSync`](/docs/edge-compute/stateful-actors/api-reference/storage#transactionsync-fn) creates every table in one transaction. Either all of them exist or none does. **Do not roll back across 0.13.0.** An SDK older than the migration does not look in the SQL database and reads a migrated instance as empty. Its data is still stored, but invisible to that code. Upgrading is safe; downgrading is not. ## WebSockets The agent's sockets are Stateful Actor WebSockets, and their [limits](/docs/edge-compute/stateful-actors/websockets/lifecycle#limits) apply unchanged. - A connection is capped at one hour from the handshake, even while frames flow. It ends with close code `1006`, and the client reconnects to the same name, where the history, the state and the pending tasks remain. - Frames that arrive while a handler runs queue up to 256 events or 1 MiB. Past that, the socket closes with `1013`. - `send` and `broadcast` [go out at once](/docs/edge-compute/stateful-actors/websockets#messages-are-single-threaded-like-everything-else), not after the write that prompted them commits. A frame that carries the message log's `seq` lets a client detect a gap and read again on reconnect. ## Actor id length An agent's name becomes an actor id, and that id is carried into names the platform builds for the instance behind it — including the file its persistent state is kept in, which is capped at 255 bytes. The budget is measured on the id **once URL-escaped**, so a `:` costs three characters rather than one, and the ceiling is **225** escaped characters: 225 ASCII characters, 54 two-byte, 36 three-byte, or 27 four-byte (emoji), plus 6 for every escaped run. [`encodeAgentName()`](/docs/agent-sdk/internals/mount/encodeAgentName) and [`mountAgents()`](/docs/agent-sdk/internals/mount/mountAgents) apply the rule. The two exports below are for a front door written by hand. Worth knowing either way: an over-long id is not rejected on first use. The instance activates and accepts writes, and only becomes unreachable once it is evicted and rehydrated, so a name that is too long looks healthy until the first eviction. ## MAX_ESCAPED_ACTOR_ID_LENGTH ## escapedActorIdLength() ## MAX_AGENT_NAME_LENGTH ## What's shipped - `Agent` base class with message history, scheduled tasks, and merge-patch state - WebSocket termination via [`webSocket()`](/docs/agent-sdk/interface/webSocket) - The agent socket layer *(SDK ≥ 0.10.0)* — [AgentClient](/docs/agent-sdk/client-sdk/constructor) for browser/Node clients (automatic reconnect, state mirroring, typed RPC) and [AgentSocketServer](/docs/agent-sdk/internals/the-socket-server) on the agent side, with the [`@rpc()`](/docs/agent-sdk/interface/rpc) opt-in - `BlobStore` for blob access within actors - The mount front door *(SDK ≥ 0.12.0)* — [`mountAgents()`](/docs/agent-sdk/internals/the-mount) routes every agent a function serves on one address shape; see [Mounting Agents](/docs/agent-sdk/mounting-agents) The `Agent` API surface may change as pieces land. --- ### The Package > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk.md The Agent Client SDK ships in the runtime package as `@telnyx/edge-runtime/client`. Its main export is the `AgentClient` class. Anything outside an agent that reaches it, a browser page or a Node app, uses the client. The client speaks the agent socket protocol to an instance's address; see [The Address and Transports](/docs/agent-sdk/contract/address-and-transports) for detail. | Export | What it is | |---|---| | `@telnyx/edge-runtime/client` | The `AgentClient` class. It has no server dependencies and runs in a browser or in Node 22 and later. | The pages document the `AgentClient` class. **The Interface** is what is exposed to the app above, the class and what a client has. | Group | What it is for | |---|---| | [Connection](/docs/agent-sdk/client-sdk/constructor) | Open a connection to an instance, read what it may do, and close it. | | [Streams](/docs/agent-sdk/client-sdk/onState) | Follow an instance's state, messages and events. | | [RPC](/docs/agent-sdk/client-sdk/stub) | Call an instance's methods. | --- ### new AgentClient() > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/constructor.md ## Type Parameters | Parameter | Constraint | Default | Meaning | |---|---|---|---| | `TStub` | `extends Record Promise>` | None | The agent's remote-callable methods, typed as `stub`. | | `TState` | None | None | The shape of the agent's state, as `onState` listeners receive it. | ## The Address The `url` is the address of one instance. [`mountAgents`](/docs/agent-sdk/mounting-agents) serves every instance it mounts at an address of this shape. ```text wss:///agents// ``` - `/agents` is the mount's default base path. - `` is a key of the mount map. - `` is the instance's routing name. Behind a hand-written front door, the address is the one that front door serves. ## Attach Mode Attach mode opens every connection, reconnects included, with an `attach` frame. The frame carries the token, the requested streams and, with `resume`, the cursors. The server answers with the granted claims and the accepted streams. [`claims`](/docs/agent-sdk/client-sdk/claims) holds the claims. Without `token`, `subscribe` or `resume`, the client speaks the plain protocol. Each connection opens with snapshots of the state and the messages, followed by `hello`. The plain protocol works with servers that speak nothing else. ## Reconnects The client reconnects on its own whenever the link drops. Only [`close`](/docs/agent-sdk/client-sdk/close) stops it. A heartbeat detects a link that died without closing. The client replaces such a link as it does a dropped one. The backoff and heartbeat options in [AgentClientOptions](#agentclientoptions) set the timing. ## AgentClientOptions ## Stream --- ### claims > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/claims.md ## Across Reconnects Claims belong to one connection. The list empties when the link drops. The next connection's `attached` answer fills it again. --- ### isConnected() > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/isConnected.md ## Across Reconnects `isConnected()` returns `false` from the moment the link drops until the next connection's `hello`. --- ### close() > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/close.md --- ### onState() > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/onState.md ## The Local Copy The client keeps a local copy of the agent's state. Every connection, reconnects included, starts the copy from a snapshot. Each [`setState`](/docs/agent-sdk/interface/setState) on the agent then arrives as an RFC 7396 merge patch. Each [`replaceState`](/docs/agent-sdk/interface/replaceState) arrives as a new snapshot. A listener receives the whole copy after every change. A listener added after the first snapshot is called at once with the current copy. --- ### onMessages() > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/onMessages.md ## The Message Stream Each item is one of the agent's [stored messages](/docs/agent-sdk/interface/messages#storedmessage). The client types the items `unknown`. Every message the agent adds to [`this.messages`](/docs/agent-sdk/interface/messages) arrives in `appended`. A listener added after the first snapshot is called at once with the current log, as a `snapshot`. --- ### onEvents() > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/onEvents.md ## The Event Stream Each [`this.events.emit`](/docs/agent-sdk/interface/events#emit) on the agent arrives as one [`AgentEvent`](#agentevent). The first connection replays the events the agent retains. Without [`resume`](/docs/agent-sdk/client-sdk/constructor#agentclientoptions), every reconnect replays them again. A listener then receives earlier events more than once. A listener receives only the events that arrive after it is added. The client keeps no copy of past events. ## AgentEvent --- ### stub > Source: https://developers.telnyx.com/docs/agent-sdk/client-sdk/stub.md ## While the Link Is Down A call made while no connection is ready waits in a buffer. The client sends it once a connection is ready. When the link drops, or a connection attempt fails, every call still waiting for an answer rejects. That includes the buffered calls. The client does not resend a rejected call. --- ## Agent Sandboxes ### Overview > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes.md A sandbox is an isolated computer that runs untrusted code. Agent Sandboxes is the platform that composes, controls, and hosts sandboxes at scale. ## Introduction The [Quick Start](/docs/edge-compute/sandboxes/quick-start) gets code running in a sandbox and reachable on a public URL. [Architecture](/docs/edge-compute/sandboxes/architecture) dives into the separation of the control plane, which acts **on** a sandbox, and the data plane, which acts **in** it. [Authentication](/docs/edge-compute/sandboxes/authentication) covers the credential each plane requires. [Limitations](/docs/edge-compute/sandboxes/limitations) lists the current product constraints. ## Runtime Every sandbox is created and managed through the same common control plane, whatever its runtime, from the API or the `telnyx-edge` CLI. [Creation](/docs/edge-compute/sandboxes/common-control-plane/creation) and [Operations](/docs/edge-compute/sandboxes/common-control-plane/operations) cover creating, listing, reading, and updating sandboxes. [User-Controlled Lifecycle](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle) and [Platform-Managed Lifecycle](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle) cover how a sandbox moves between its states, by request and on its own. [Snapshots](/docs/edge-compute/sandboxes/common-control-plane/snapshots) keep a running sandbox's state for new sandboxes to start from, and [Network Limits](/docs/edge-compute/sandboxes/common-control-plane/network-limits) control where a sandbox connects. [Composition](/docs/edge-compute/sandboxes/composition) details the composability of sandboxes. [Linux](/docs/edge-compute/sandboxes/linux) is the sandbox type available today. ## Platform Properties [Isolation](/docs/edge-compute/sandboxes/platform-properties/isolation), [Persistence](/docs/edge-compute/sandboxes/platform-properties/persistence), [Scale](/docs/edge-compute/sandboxes/platform-properties/scale), and [Regions](/docs/edge-compute/sandboxes/platform-properties/regions) explain the properties every sandbox has. They cover what separates a sandbox from the host and from other sandboxes, what it keeps across a pause, a snapshot, or a fork, how many sandboxes run at once, and where a sandbox runs. ## Organization Resources [Organization resources](/docs/edge-compute/sandboxes/organization-resources) belong to the organization, not to any one sandbox. They sit beside the sandbox resource rather than under a sandbox ID, and sandboxes use them. [Templates](/docs/edge-compute/sandboxes/organization-resources/templates) start a sandbox with its server already listening, and [Secrets](/docs/edge-compute/sandboxes/organization-resources/secrets) let code in a sandbox use credentials that the sandbox never holds. ## Data Plane Operations An agent works inside a sandbox on every turn through the data plane. It runs commands as [Execs](/docs/edge-compute/sandboxes/data-plane-operations/execs), reaches the sandbox's [Main Command](/docs/edge-compute/sandboxes/data-plane-operations/main-command), and moves [Files](/docs/edge-compute/sandboxes/data-plane-operations/files). [Metrics](/docs/edge-compute/sandboxes/data-plane-operations/metrics) and [Lifecycle Events](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) record each sandbox's resource use and state changes. ## Out-of-Band Access [Ports](/docs/edge-compute/sandboxes/out-of-band-access/ports) put any HTTP or WebSocket server in a sandbox on its own public URL, reached outside the API by browsers, services, and other agents. ## Platform [Limits](/docs/edge-compute/sandboxes/platform/limits) lists every product limit and retention period. [Billing](/docs/edge-compute/sandboxes/platform/billing) explains resource usage, account information, and cleanup. [Errors](/docs/edge-compute/sandboxes/platform/errors) lists every error code the API returns. --- ### Quick Start > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/quick-start.md This guide creates a sandbox, writes and runs a Python script in it, serves an HTTP port from it, pauses and resumes it, and terminates it, with the `telnyx-edge` CLI and with the API. These examples require a Sandbox-enabled account and a `telnyx-edge` release containing the `sandbox-cpu` commands. The canonical [Sandbox OpenAPI contract](https://api.telnyx.com/v2/compute/sandbox/openapi.json) describes the supported API operations. The `telnyx-edge` CLI has commands for every documented operation (token minting is automatic), including `batch`, `fork`, `snapshot`, `template`, `network`, `logs`, `metrics`, `events`, and file management (`ls`, `stat`, `mkdir`, `mv`, `rm`). Run `telnyx-edge sandbox-cpu --help` for commands and flags. Lifecycle requests go to the control plane at `api.telnyx.com` with the API key. Execs and files go to the data plane in the sandbox's region with a token. The CLI sends both and handles the token itself. See [Architecture](/docs/edge-compute/sandboxes/architecture). ## Prerequisites - The `telnyx-edge` CLI v0.6.0 or newer. See [Installation](/docs/edge-compute/reference/cli#installation), then run `telnyx-edge update` (or `sudo telnyx-edge update` if installed in `/usr/local/bin`) to get the latest version with `sandbox-cpu` commands. - A Telnyx API key, stored for the CLI and in `TELNYX_API_KEY` for the API. See [Create API Keys](/docs/development/api-fundamentals/create-api-keys). - `curl` and `jq` for the API requests. ```bash Workstation telnyx-edge auth api-key set $TELNYX_API_KEY ``` ## 1. Create a Sandbox Create a sandbox from the official Python image, with a 30-minute lifetime. The CLI waits until the sandbox is `running` and prints its ID. ```bash Workstation telnyx-edge sandbox-cpu create \ --image docker.io/library/python:3.12-slim \ --name doc-quick-start \ --timeout 1800 ``` ```bash API export CONTROL_API=https://api.telnyx.com/v2/compute/sandbox CREATE_RESPONSE=$(curl --fail-with-body -sS -X POST "$CONTROL_API" \ -H "Authorization: Bearer $TELNYX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image": { "ref": "docker.io/library/python:3.12-slim" }, "name": "doc-quick-start", "timeout": 1800 }') || { echo "Sandbox create failed" >&2; exit 1; } export SANDBOX_ID=$(echo "$CREATE_RESPONSE" | jq -er '.data.id') || exit 1 echo "$SANDBOX_ID" ``` The ID names the sandbox's region. Sandbox IDs, region selection, and startup times vary. The first sandbox from an image also builds the image, which takes longer than later creates. With the API, the sandbox may initially be `starting`. Poll until it is `running` before proceeding. ```bash API while :; do STATUS_RESPONSE=$(curl --fail-with-body -sS "$CONTROL_API/$SANDBOX_ID" \ -H "Authorization: Bearer $TELNYX_API_KEY") || exit 1 STATE=$(echo "$STATUS_RESPONSE" | jq -er '.data.state') || exit 1 case "$STATE" in running) echo "$STATUS_RESPONSE" | jq '.data | {state, expires_at}' break ;; terminated|failed) echo "Sandbox entered $STATE before becoming ready" >&2 exit 1 ;; starting) sleep 2 ;; *) echo "Unexpected sandbox state: $STATE" >&2 exit 1 ;; esac done ``` ## 2. Get a Token With the API, request a token from the control plane, and keep it with the base URL of the data plane in the sandbox's region. The CLI mints and caches the token itself, so it has no step here. ```bash API RESPONSE=$(curl --fail-with-body -sS -X POST "$CONTROL_API/token" \ -H "Authorization: Bearer $TELNYX_API_KEY") || exit 1 export SANDBOX_TOKEN=$(echo "$RESPONSE" | jq -er .data.token) || exit 1 export SANDBOX_REGION=$(echo "$SANDBOX_ID" | sed -E 's/^sb-(.*)-[0-9a-f]{8}-[0-9a-f-]{27}$/\1/') export REGION_BASE=$(echo "$RESPONSE" | jq -r --arg region "$SANDBOX_REGION" '.data.regions[$region] // empty') test -n "$REGION_BASE" || { echo "Sandbox region is not in the token response" >&2; exit 1; } export DATA_API="$REGION_BASE/v2/compute/sandbox" ``` The token is valid for one hour in every region. See [Authentication](/docs/edge-compute/sandboxes/authentication). ## 3. Write a File Write a script into the workspace disk. ```bash Workstation cat > primes.py <<'EOF' import json primes = [n for n in range(2, 100) if all(n % d for d in range(2, int(n ** 0.5) + 1))] result = {"count": len(primes), "largest": primes[-1]} json.dump(result, open("/workspace/result.json", "w")) print(f"found {len(primes)} primes") EOF ``` ```bash Workstation telnyx-edge sandbox-cpu cp primes.py \ doc-quick-start:/workspace/primes.py ``` ```bash API curl -s -X PUT \ "$DATA_API/$SANDBOX_ID/files?path=/workspace/primes.py" \ -H "Authorization: Bearer $SANDBOX_TOKEN" \ --data-binary @primes.py | jq .data.size_bytes ``` ## 4. Run It Run the script as an exec. The CLI streams the script's output and exits with its exit code. With the API, start the exec, then wait up to 10 seconds for it to finish. ```bash Workstation telnyx-edge sandbox-cpu exec doc-quick-start \ -- python3 /workspace/primes.py ``` ```bash API EXEC_ID=$(curl -s -X POST $DATA_API/$SANDBOX_ID/exec \ -H "Authorization: Bearer $SANDBOX_TOKEN" \ -H "Content-Type: application/json" \ -d '{"command": ["python3", "/workspace/primes.py"]}' \ | jq -r .data.id) curl -s "$DATA_API/$SANDBOX_ID/exec/$EXEC_ID?wait=10" \ -H "Authorization: Bearer $SANDBOX_TOKEN" \ | jq '.data | {status, exit_code}' ``` Read the file the script wrote. With `-`, the CLI writes the file to stdout, and `-q` drops its summary line. ```bash Workstation telnyx-edge sandbox-cpu cp -q \ doc-quick-start:/workspace/result.json - ``` ```bash API curl -s \ "$DATA_API/$SANDBOX_ID/files?path=/workspace/result.json" \ -H "Authorization: Bearer $SANDBOX_TOKEN" ``` The exec's output also streams over its attach WebSocket. See [Execs](/docs/edge-compute/sandboxes/data-plane-operations/execs#output). ## 5. Serve a Port Start an HTTP server on port 8000 as a second exec. It keeps running beside other execs. The CLI's `exec` streams until its command ends, so the server is started in the background inside the sandbox and the exec returns at once. ```bash Workstation telnyx-edge sandbox-cpu exec doc-quick-start \ --workdir /workspace \ -- sh -c 'nohup python3 -m http.server 8000 >/dev/null 2>&1 &' ``` ```bash API curl -s -X POST $DATA_API/$SANDBOX_ID/exec \ -H "Authorization: Bearer $SANDBOX_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "command": ["python3", "-m", "http.server", "8000"], "workdir": "/workspace" }' | jq -r .data.status ``` Request the file from the internet on the port's URL. ```bash Shell curl --retry 10 --retry-delay 1 --retry-all-errors --fail-with-body -sS "https://$SANDBOX_ID-8000.$SANDBOX_REGION.sandbox.telnyxcompute.com/result.json" ``` Anyone with this URL reaches the port. See [Ports](/docs/edge-compute/sandboxes/out-of-band-access/ports) to require a traffic token. ## 6. Pause and Resume Pause the sandbox. Its memory, processes, and files are saved, and it stops using CPU. The CLI waits until the sandbox is `paused`. ```bash Workstation telnyx-edge sandbox-cpu pause doc-quick-start ``` ```bash API curl -s -X POST $CONTROL_API/$SANDBOX_ID/pause \ -H "Authorization: Bearer $TELNYX_API_KEY" > /dev/null curl -s "$CONTROL_API/$SANDBOX_ID/wait?timeout=10" \ -H "Authorization: Bearer $TELNYX_API_KEY" \ | jq '.data | {state, remaining}' ``` Resume it. The CLI's `resume` waits until the sandbox runs again. With the API, `connect` resumes it and extends its lifetime, as an agent does at the start of each turn. ```bash Workstation telnyx-edge sandbox-cpu resume doc-quick-start ``` ```bash API curl -s -X POST $CONTROL_API/$SANDBOX_ID/connect \ -H "Authorization: Bearer $TELNYX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"timeout": 900}' | jq .data.state ``` Once the sandbox is `running` again, the HTTP server is still serving. It resumed from where it paused, without a restart. ```bash Shell curl -s https://$SANDBOX_ID-8000.$SANDBOX_REGION.sandbox.telnyxcompute.com/result.json ``` ## 7. Terminate Terminate the sandbox. The CLI asks for a confirmation, which `--yes` skips. ```bash Workstation telnyx-edge sandbox-cpu terminate --yes doc-quick-start ``` ```bash API curl -s -X POST $CONTROL_API/$SANDBOX_ID/terminate \ -H "Authorization: Bearer $TELNYX_API_KEY" | jq .data.state ``` The sandbox's memory, disks, and snapshots are discarded. ## Next Steps - [Templates](/docs/edge-compute/sandboxes/organization-resources/templates) start a sandbox with its server already running. - [Fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) copies a running sandbox into many. - [Network Limits](/docs/edge-compute/sandboxes/common-control-plane/network-limits) restrict where a sandbox connects. - [Secrets](/docs/edge-compute/sandboxes/organization-resources/secrets) give a sandbox credentials it never sees. --- ### Architecture > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/architecture.md Agent Sandboxes has two planes. The **control plane** manages sandboxes. It creates them, changes their state, and terminates them, in every region from one endpoint. The **data plane** is where a sandbox is used. It runs commands, moves files, streams output, and carries traffic to ports, in the sandbox's own region. The control plane acts **on** a sandbox. The data plane acts **in** one. ## Control Plane The control plane is the Telnyx API at `https://api.telnyx.com`. It is one endpoint for every region, and the only one that requires a Telnyx API key. It stops at the edge of a sandbox and never reaches inside one, so it answers `404` for a data-plane request. The control plane serves these resources. - [`/v2/compute/sandbox`](/docs/edge-compute/sandboxes/common-control-plane/creation) lists and creates sandboxes. - [`/batch`](/docs/edge-compute/sandboxes/common-control-plane/creation#batch-create) creates many sandboxes at once. - [`/{sandbox_id}`](/docs/edge-compute/sandboxes/common-control-plane/operations#read) reads a sandbox and sets its tags. - [`/wait`](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#wait) waits for a pause or a terminate. - [`/connect`](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#connect) resumes the sandbox and extends its lifetime. - [`/pause`](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#pause-and-resume), [`/resume`](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#pause-and-resume), and [`/terminate`](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#terminate) move it between its states. - [`/timeout`](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle#timeout) sets its lifetime. - [`/fork`](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) copies it into many sandboxes. - [`/snapshot`](/docs/edge-compute/sandboxes/common-control-plane/snapshots) takes and lists snapshots. - `/{snapshot_id}` reads and deletes a snapshot. - [`/network`](/docs/edge-compute/sandboxes/common-control-plane/network-limits) changes its outbound policy. - [`/template`](/docs/edge-compute/sandboxes/organization-resources/templates) lists and creates templates. - `/{template_id}` reads and deletes a template. - `/rebuild` rebuilds it. - [`/token`](/docs/edge-compute/sandboxes/authentication#sandbox-token) issues a token. - [`/v2/compute/secrets`](/docs/edge-compute/sandboxes/organization-resources/secrets) holds the organization's secrets. ## Data Plane Each region has its own data plane at `https://api..sandbox.telnyxcompute.com`. It requires a token, never an API key. It stops at the edge of its region, serves only that region's sandboxes, and issues no tokens. The data plane serves these resources for its own region. - `/v2/compute/sandbox` - `/{sandbox_id}` - [`/exec`](/docs/edge-compute/sandboxes/data-plane-operations/execs) runs and lists execs, in a [PTY](/docs/edge-compute/sandboxes/data-plane-operations/execs#pty) when asked. - `/{exec_id}` reads an exec. - `/attach` streams its output and writes its stdin. - `/kill` signals it. - `/stdin/close` closes its stdin. - [`/attach`](/docs/edge-compute/sandboxes/data-plane-operations/main-command#attach) writes the main command's stdin and returns its exit code. - [`/stdin/close`](/docs/edge-compute/sandboxes/data-plane-operations/main-command#stdin) closes the main command's stdin. - [`/logs`](/docs/edge-compute/sandboxes/data-plane-operations/main-command#logs) returns the main command's logs. - [`/files`](/docs/edge-compute/sandboxes/data-plane-operations/files) reads, writes, lists, and deletes files. - `/rename` renames a file or directory. - [`/metrics`](/docs/edge-compute/sandboxes/data-plane-operations/metrics) returns the sandbox's resource usage. - [`/lifecycle_event`](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) lists the sandbox's lifecycle events. - [`/lifecycle_event`](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) lists every sandbox's lifecycle events. [Port traffic](/docs/edge-compute/sandboxes/out-of-band-access/ports) reaches a port in a sandbox at `https://-..sandbox.telnyxcompute.com`, for HTTP and WebSocket requests. Ports are public by default. The line between acting **on** a sandbox and acting **in** it has two exceptions, both on the data plane. - **Management at the region.** The data plane also accepts management requests for its own region, at the same paths as the control plane, so a client that holds a token can pause or resume a sandbox without the control plane. - **Records of a sandbox.** Lifecycle events and metrics describe a sandbox from the outside, yet are read from the data plane, not the control plane, because each region keeps the record of its own sandboxes. A region's data plane keeps serving clients that hold a valid token in the event of a control plane outage. --- ### Authentication > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/authentication.md Agent Sandboxes requires two credentials, one for each plane. A Telnyx API key authenticates requests at the control plane. A short-lived token authenticates requests at a region's data plane. Both are sent as `Authorization: Bearer`. | Credential | Plane | Host | | --- | --- | --- | | Telnyx API key | Control plane | `api.telnyx.com` | | Sandbox token | Data plane | `api..sandbox.telnyxcompute.com` | See [Architecture](/docs/edge-compute/sandboxes/architecture) for the requests each plane serves. ## API Key A Telnyx API key authenticates every request to the control plane at `https://api.telnyx.com`. Create one in the [Telnyx Portal](https://portal.telnyx.com/#/api-keys). See [Create API Keys](/docs/development/api-fundamentals/create-api-keys). The request below creates a sandbox with the API key. The CLI reads the key stored by `telnyx-edge auth api-key set`. ```bash Workstation telnyx-edge sandbox-cpu create \ --image docker.io/library/python:3.12-slim ``` ```bash API curl -X POST https://api.telnyx.com/v2/compute/sandbox \ -H "Authorization: Bearer $TELNYX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image": {"ref": "docker.io/library/python:3.12-slim"}}' ``` ## Sandbox Token A token authenticates requests at a region's data plane. The control plane issues it for the API key's organization. ```bash API curl -X POST https://api.telnyx.com/v2/compute/sandbox/token \ -H "Authorization: Bearer $TELNYX_API_KEY" ``` The response carries the token, its expiry, and the base URL of every region. ```json Output { "data": { "token": "eyJhbGciOiJIUzI1NiIsImtpZCI6InByb2QtMSJ9...", "expires_at": "2026-11-11T19:04:05Z", "regions": { "us-east-1": "https://api.us-east-1.sandbox.telnyxcompute.com" } } } ``` The token is valid for one hour in every region. A request with a missing, expired, or altered token receives `401`. The token is checked when a request starts, so an exec stream or a WebSocket opened with it stays open after it expires. The CLI uses the API key for the control plane, and mints and caches the data-plane token itself. A data-plane request carries the token in the same header. The data-plane examples on the other pages write the region's base URL with `/v2/compute/sandbox` appended as `$DATA_API`. ```bash API DATA_HOST=https://api.us-east-1.sandbox.telnyxcompute.com DATA_API=$DATA_HOST/v2/compute/sandbox curl $DATA_API -H "Authorization: Bearer $SANDBOX_TOKEN" ``` --- ### Limitations > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/limitations.md Agent Sandboxes has the following limitations. Each row links to the page that explains the constraint. | Area | Limitation | Details | | --- | --- | --- | | Regions | Sandboxes run in one region, `us-east-1`. More regions come as separate deployments. | [Regions](/docs/edge-compute/sandboxes/platform-properties/regions) | | Sizes | A sandbox has 1 or 2 vCPU, 256 to 4096 MiB of memory, an 8 GiB root disk, and a 16 GiB workspace disk. | [Composition](/docs/edge-compute/sandboxes/composition#size) | | Images | An image must offer `linux/amd64`, and its reference must name its registry host. | [Linux](/docs/edge-compute/sandboxes/linux#image-requirements) | | Quotas | An organization runs up to 20 sandboxes `starting` or `running` and holds up to 20 templates in each region, then `429 quota_exceeded`. A fork's source holds a slot, so the largest fork is 19 siblings. Four file transfers over 8 MiB run at once per organization on each API replica, then `503` with `Retry-After`. | [Scale](/docs/edge-compute/sandboxes/platform-properties/scale#capacity) | | Request rate | The control plane accepts 20 requests per second with one API key, then `429`. The data plane sets no request rate limit. | [Errors](/docs/edge-compute/sandboxes/platform/errors#general-errors) | | Snapshots | A sandbox holds up to 3 snapshots, which are removed with it. Publishing a snapshot as a template is not available yet. | [Snapshots](/docs/edge-compute/sandboxes/common-control-plane/snapshots) | | Templates | Tags that pin a create to one build are not available yet. | [Templates](/docs/edge-compute/sandboxes/organization-resources/templates) | | Warm pools | Warm pools of started sandboxes are not available yet. | [Scale](/docs/edge-compute/sandboxes/platform-properties/scale) | | Stop and archive | A sandbox pauses or terminates. There is no disk-only stop or archive tier, and a paused sandbox is kept 7 days. | [Platform-Managed Lifecycle](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle#paused-retention) | | Volumes | There are no persistent volumes. The workspace disk lives with the sandbox. | [Persistence](/docs/edge-compute/sandboxes/platform-properties/persistence#disk-persistence) | | GPU | A sandbox has no GPU. | [Linux](/docs/edge-compute/sandboxes/linux#virtual-machine) | | Git and code tools | There are no git, code-run, or LSP routes. An exec runs those tools. | [Execs](/docs/edge-compute/sandboxes/data-plane-operations/execs) | | Ports | Every port is reachable at its URL, and the traffic token is the only access control. There are no signed URLs. | [Ports](/docs/edge-compute/sandboxes/out-of-band-access/ports#access) | | Access control | One organization API key and a 1-hour data-plane token authenticate every request. There are no scoped keys and no audit log. | [Authentication](/docs/edge-compute/sandboxes/authentication) | | Webhooks | Lifecycle events are read by request. Webhooks are not available yet. | [Lifecycle Events](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events#webhooks) | --- ### Creation > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/creation.md A sandbox is created with one request through the control plane. The request names the sandbox's source and sets its other parts, and a batch creates many sandboxes of one definition at once. `POST /sandbox` creates a sandbox. The create names one source and sets the rest of the sandbox's parts, each described in [Composition](/docs/edge-compute/sandboxes/composition#parts). The response is `201` with the sandbox in `starting`. The request below creates a 2 vCPU sandbox from the official Python image. The CLI waits until the sandbox is `running` and prints its ID. ```bash Workstation telnyx-edge sandbox-cpu create \ --image docker.io/library/python:3.12-slim \ --name doc-run-42 \ --tag task=data-cleanup \ --cpu 2 \ --memory 2048 \ --timeout 1800 \ --idle-timeout 300 \ --env PYTHONUNBUFFERED=1 ``` ```bash API curl -X POST https://api.telnyx.com/v2/compute/sandbox \ -H "Authorization: Bearer $TELNYX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c2a9e-run-42" \ -d '{ "image": { "ref": "docker.io/library/python:3.12-slim" }, "name": "doc-run-42", "tags": { "task": "data-cleanup" }, "cpu": 2, "memory_mib": 2048, "timeout": 1800, "idle_timeout": 300, "env": { "PYTHONUNBUFFERED": "1" } }' ``` ```text Output Waiting for sandbox sb-us-east-2-01a1d715-ca93-760b-a01b-20d1b9ee4865 to be running... sb-us-east-2-01a1d715-ca93-760b-a01b-20d1b9ee4865 ``` ## Batch Create `POST /sandbox/batch` creates up to 10 sandboxes of one definition. The body is a create body with a `count`. `from` is allowed. ```json Request { "count": 3, "template": "web-agent", "name": "grader", "timeout": 900 } ``` The response is `200` with one entry per item, and the totals. ```json Output { "items": [ { "index": 1, "sandbox": { "id": "sb-us-east-1-...", "name": "grader-1", "state": "starting", ... } }, { "index": 2, "sandbox": { "id": "sb-us-east-1-...", "name": "grader-2", "state": "starting", ... } }, { "index": 3, "error": { "code": "90019", "title": "no_capacity", ... } } ], "created": 2, "failed": 1 } ``` `index` counts the items from 1, and item `i` of a named batch is `-`. A batch past the quota is refused whole with `429 quota_exceeded`. A batch no host admits is refused with `503 no_capacity`. --- ### Operations > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/operations.md A sandbox is listed, read, and updated through these operations. None of them moves it between its [states](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#states). ## List `GET /sandbox` lists sandboxes, newest first, 20 per page and at most 100. The filters are `name`, `state`, which repeats, `tag[]`, and `swarm`. Without `state`, terminated sandboxes are omitted, and they stay readable for at least 30 days. The control plane lists every region's sandboxes, and a region's data plane lists its own. See [Regions](/docs/edge-compute/sandboxes/platform-properties/regions#listing-across-regions). `telnyx-edge sandbox-cpu list` filters by `--name`, `--state`, and `--region`. ## Read `GET /sandbox/{id}` returns one sandbox. A sandbox of another organization is `404`. The response below shows a few of its fields. ```json Output { "data": { "id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d", "region": "us-east-1", "name": "run-42", "tags": { "task": "data-cleanup" }, "state": "running", "cpu": 2, "memory_mib": 2048, ... } } ``` The object carries the sandbox's [parts](/docs/edge-compute/sandboxes/composition#parts), its [state](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#states), and its [lifetime](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle). `env` and `rules` keep their markers, never secret values, and `registry_secret` is never returned. `telnyx-edge sandbox-cpu get` reads one sandbox by ID or name, as a table or as JSON with `--json`. ## Update `PATCH /sandbox/{id}` replaces the whole tag set with `{"tags": {...}}`, and `{}` clears it. An update changes tags only, and is accepted on a terminated sandbox. The outbound policy and the timeout have their own requests, [`/network`](/docs/edge-compute/sandboxes/common-control-plane/network-limits) and [`/timeout`](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle#timeout). --- ### User-Controlled Lifecycle > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle.md A sandbox moves between four states. Requests pause, resume, and terminate it, an agent connects to it at the start of each turn, and a fork copies a running sandbox into many. ## States A sandbox is always in one of four states. Each arrow below is a request or an event that moves it to the next. The diagram shows the four states. A sandbox goes from `starting` to `running`. A pause request, the idle timeout, or the timeout with `on_timeout` `pause` moves it to `paused`, and a resume or a connect moves it back to `starting`. It reaches `terminated` from `starting` on a failure, from `running` on a terminate request, a timeout, or the main command's exit, and from `paused` on a terminate request or the end of its paused retention. | `state` | Meaning | | --- | --- | | `starting` | Being placed, built, booted, restored, or resumed. | | `running` | Running. A pause or a snapshot in progress still reads `running`. | | `paused` | Memory, processes, and disks saved. No CPU used. | | `terminated` | Ended. `termination_reason` says why. See [Terminate](#terminate). | `started_at` is set when the boot starts. The sandbox reads `running` with `ready` `true` about 2 seconds later, and the `started` [lifecycle event](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events#event-types) marks that moment. ## Pause and Resume `POST /sandbox/{id}/pause` pauses a `running` sandbox. The response is `202`. The sandbox reads `running` until the pause completes, then `paused`, with `paused_at` and a `pause_reason` of `customer`, `idle_timeout`, or `timeout`. See [Persistence](/docs/edge-compute/sandboxes/platform-properties/persistence#memory-persistence) for what a pause keeps. `POST /sandbox/{id}/resume` restores a `paused` sandbox on the same host. The response is `202`, and the sandbox reads `starting`, then `running`. A resume when the organization is at its quota is refused with `429 quota_exceeded`, and the sandbox stays paused. Execs and file requests to a paused sandbox are refused with `409 sandbox_paused`. `telnyx-edge sandbox-cpu pause` and `resume` send the same requests and wait for the state. ## Connect `POST /sandbox/{id}/connect` is the request an agent sends at the start of each turn. ```json Request { "timeout": 600 } ``` - On a `paused` sandbox, it starts the resume and answers `202` once the resume is under way, after several seconds. - On a `running` sandbox, it answers `200`, and on a `starting` one `202`. - On every sandbox, it moves `expires_at` to at least now plus `timeout`, never earlier. `timeout` defaults to 300 seconds, and `null` leaves the expiry unchanged. The sandbox's `timeout` field stays as created. A connect counts as activity for `idle_timeout`. ## Terminate `POST /sandbox/{id}/terminate` ends a sandbox in any state and discards its memory, disks, and snapshots. The response is `202`, and the sandbox reads `terminated` once the host has released it. A second terminate answers `202` with the sandbox unchanged. `telnyx-edge sandbox-cpu terminate` sends it after a confirmation, which `--yes` skips. A terminated sandbox's `termination_reason` says why it ended. | `termination_reason` | Cause | | --- | --- | | `terminated` | A terminate request. | | `exited` | The main command exited. `exit_code` is set. | | `timeout` | The `timeout` passed with `on_timeout` `terminate`. | | `idle_timeout` | The `idle_timeout` passed with `on_idle` `terminate`. | | `paused_expired` | The sandbox stayed paused past the retention period. | | `build_failed` | The image could not be pulled or built. | | `no_capacity` | A fork sibling no host could place. | | `node_lost` | The sandbox's host failed. | | `internal_error` | The platform failed. | ## Wait `GET /sandbox/{id}/wait?timeout=10` returns once the sandbox is `paused` or `terminated`, or after `timeout` seconds, at most 10. `timeout=0` answers at once, and a larger value is capped at 10. A client uses it to wait for a pause or a terminate to complete. ## Fork `POST /sandbox/{id}/fork` creates up to 20 siblings of a `running` sandbox, each with its memory, processes, and disks as they are now. ```json Request { "count": 5, "name": "attempt", "tags": { "branch": "refactor" } } ``` The response is `202` at once, with every sibling in `starting`. ```json Output { "items": [ { "index": 1, "sandbox": { "id": "sb-us-east-1-0193c4d3-...", "name": "attempt-1", "state": "starting", "fork_of": "sb-us-east-1-0193c4d2-...", "swarm": "swm-0193c4d3-...", ... } }, ... ], "swarm": "swm-0193c4d3-..." } ``` - **Live state.** Each sibling starts from the source's state at the moment of the fork. The source's processes stand still while that state is saved, about 10 seconds at 1 GiB, with its state reading `running`, and continue afterwards. - **Names and tags.** A sibling's name is `-`, with `index` counted from 1. Its tags are the source's, with the request's tags merged over them. - **Swarm.** The source and every sibling share one `swarm` ID for their whole lives, and a fork of a sibling joins the same swarm. `GET /sandbox?swarm=` lists them. - **Placement.** A sibling no host can place reads `terminated` with `termination_reason` `no_capacity`. A fork of a sandbox that is not `running` is refused with `409 sandbox_not_running`. A fork past the quota is refused whole with `429 quota_exceeded`. The source holds a slot of the quota, so the largest fork under the default quota of 20 is 19 siblings. --- ### Platform-Managed Lifecycle > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle.md A sandbox pauses or terminates on its own when its timeout or its idle timeout passes. Both are set on the create, and the timeout can be changed while the sandbox exists. A paused sandbox also terminates once its retention period ends. ## Timeout `timeout` is the sandbox's lifetime in seconds of running. It defaults to `300`, and `null` means none. The clock starts at `started_at` and stops while the sandbox is paused. When it passes, `on_timeout` applies. | `on_timeout` | Effect | | --- | --- | | `terminate` (default) | The sandbox terminates with `termination_reason` `timeout`. | | `pause` | The sandbox pauses with `pause_reason` `timeout`. | While the sandbox is `starting` or `running`, `expires_at` is when its timeout fires. While it is `paused`, `remaining` is the number of seconds of its timeout left. `POST /sandbox/{id}/timeout` with `{"seconds": 3600}` sets the expiry to now plus `seconds`, or removes it with `null`. On a paused sandbox it sets `remaining`. A resume always grants at least 300 seconds, so a sandbox paused by its timeout runs again after a resume. `telnyx-edge sandbox-cpu timeout 3600` sends the same request, and `none` removes the timeout. ## Idle Timeout `idle_timeout` is the number of seconds without activity after which `on_idle` applies. It has no default and cannot exceed `timeout`. | `on_idle` | Effect | | --- | --- | | `pause` (default) | The sandbox pauses with `pause_reason` `idle_timeout`. | | `terminate` | The sandbox terminates with `termination_reason` `idle_timeout`. | Activity is any of the following. - An exec that starts, or one that is still running - Stdin written, or an attach held open - A file request - A connect The main command's own work is not activity. ## Paused Retention A sandbox that stays paused for 7 days terminates with `termination_reason` `paused_expired`. See [Persistence](/docs/edge-compute/sandboxes/platform-properties/persistence#retention). --- ### Snapshots > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/snapshots.md A snapshot is a named copy of a running sandbox's memory, processes, and disks. The source continues once it is taken, and new sandboxes can start from it with that state while the source sandbox exists. ## Take a Snapshot `POST /sandbox/{id}/snapshot` snapshots a `running` sandbox. `name` is optional and need not be unique. ```json Request { "name": "deps-installed" } ``` The response is `202` with the snapshot. ```json Output { "data": { "id": "snap-0193c4e1-5b2a-7d10-8c3f-2e4a6b8d0f12", "sandbox_id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d", "name": "deps-installed", "phase": "Preparing", "failure_cause": null, "created_at": "2026-11-11T19:12:40Z", "updated_at": "2026-11-11T19:12:40Z" } } ``` `phase` moves through the steps of the copy and ends at `Published` when the snapshot is usable, or `Failed` with a `failure_cause`. A larger memory size takes longer, from about 10 seconds to about a minute. The source's processes stand still while its memory is copied, about 6 to 10 seconds at 1 GiB, and its state reads `running` throughout. A paused sandbox cannot be snapshotted. A snapshot request while a pause or another snapshot is in progress is refused with `409 operation_in_progress`. ## Create from a Snapshot `from` starts a new sandbox with the snapshot's state. ```json Request { "from": { "snapshot": "snap-0193c4e1-5b2a-7d10-8c3f-2e4a6b8d0f12" }, "name": "retry-1", "timeout": 600 } ``` - **Fields.** Only `name`, `tags`, `timeout`, `idle_timeout`, and `region` may be given with `from`. The image, the sizes, the environment, and the network policy are the source's. - **Timeouts.** An omitted `timeout` or `idle_timeout` is copied from the source. - **Identity.** The new sandbox receives a new machine ID, new SSH host keys, and new entropy. - **Batches.** `POST /sandbox/batch` accepts `from`, to start many sandboxes from one snapshot. A snapshot that is not yet `Published` is refused with `409 snapshot_not_published`. A snapshot whose source has terminated is refused with `409 source_terminated`. ## Manage Snapshots | Request | Effect | | --- | --- | | `GET /sandbox/{id}/snapshot` | Lists the sandbox's snapshots, newest first. | | `GET /sandbox/{id}/snapshot/{snapshot_id}` | Returns one snapshot. | | `DELETE /sandbox/{id}/snapshot/{snapshot_id}` | Deletes the snapshot. Returns `204`. | A sandbox holds at most three snapshots. A fourth is refused with `409 snapshot_quota` until one is deleted and the host has removed its checkpoint, shortly after the delete. Pauses and forks do not count against the cap. A snapshot belongs to its source sandbox and is removed when the source terminates. Its record can read `Published` for a few minutes afterwards, while a create from it is refused with `409 source_terminated`. To keep a ready state beyond one sandbox, use a [template](/docs/edge-compute/sandboxes/organization-resources/templates). A snapshot published as a template Coming soon will keep a sandbox's live state after it terminates. ## Snapshots, Pauses, and Forks | Operation | Source Afterwards | Result | | --- | --- | --- | | Pause | Stopped, resumable | The same sandbox, resumed later | | Snapshot | Running | A named state for new sandboxes while the source exists | | Fork | Running | New sandboxes now | --- ### Network Limits > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/common-control-plane/network-limits.md Network limits control where a sandbox connects. Its outbound policy is an egress mode with optional CIDR and domain allowlists, set by `network` on the create. `PUT /sandbox/{id}/network` replaces the policy while the sandbox runs or is paused. ```json Request { "image": { "ref": "docker.io/library/python:3.12-slim" }, "network": { "egress": "allowlist", "allow_out": [ "pypi.org", "*.pythonhosted.org", "203.0.113.0/24" ] } } ``` ## Egress Modes | `egress` | Outbound Traffic | | --- | --- | | `public` (default) | Every destination outside the deny set | | `allowlist` | DNS, the `allow_out` entries, and the hosts of [secret rules](/docs/edge-compute/sandboxes/organization-resources/secrets) | | `blocked` | None, DNS included | The sandbox has no IPv6. DNS resolves public names only. The platform deny set applies under every mode, above `allow_out`. It covers `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `100.64.0.0/10`, and the host's public address. TCP port 25 is blocked to every destination under every mode. The sandbox's resolver sits inside the deny set and answers DNS on port 53 only, so an `allow_out` entry for it is refused. See [Isolation](/docs/edge-compute/sandboxes/platform-properties/isolation#network-isolation). ## Allowlist Entries `allow_out` holds up to 256 entries, CIDRs and domains together. It is accepted only under `allowlist`, and refused under the other modes with `422 allow_out_not_allowed`. | Entry | Format | Matches | | --- | --- | --- | | Address or CIDR | IPv4, host bits clear, such as `203.0.113.7` or `203.0.113.0/24` | Every port and protocol to those addresses | | Domain | ASCII, such as `pypi.org`, stored in lowercase | That name only, on TCP 443 and 80 | | Wildcard domain | `*.` and at least two labels, such as `*.pythonhosted.org` | Every name below the domain, at any depth, never the domain itself | An entry that overlaps the deny set is refused with `422 cidr_not_allowed`, and `0.0.0.0/0` is refused. An IPv6 CIDR is refused with `400`, because the sandbox has no IPv6. A malformed entry is refused with `400`, pointing at `/network/allow_out/` on a create and `/allow_out/` on a `PUT`. Duplicate entries are dropped. Internationalized names are given in punycode. ### Domain Matching A domain entry matches the TLS server name of an HTTPS connection, or the `Host` header of a plain HTTP request. The platform resolves the allowed name itself and connects to that address, never to the address the sandbox dialed. A forged server name therefore reaches only an address the allowed name resolves to. Matching applies to the first name on a connection. The rest of the connection passes through unchanged. Several sites behind one shared address remain reachable through a connection opened to an allowed name. Under `allowlist`, the following are refused to every destination outside the CIDR entries. - QUIC and every UDP port except DNS - Every TCP port except 80 and 443, which reach a domain entry's name only Under an allowlist with domain entries, a refused TCP connection to port 80 or 443 is accepted and then closed, so it may appear open for a moment from inside the sandbox. ## Changing the Policy `PUT /sandbox/{id}/network` replaces `egress` and `allow_out` on a `running` or `paused` sandbox. `egress` is required. `rules` may be omitted. When present, it must equal the sandbox's current rules, or the request is refused with `422 rules_immutable`. ```json Request { "egress": "allowlist", "allow_out": ["pypi.org", "*.pythonhosted.org"] } ``` The response is `202` for a `running` sandbox, which shows the previous policy until the host applies the new one, and `200` for a `paused` sandbox. `blocked` on a sandbox with rules is refused with `422 rules_not_allowed`. On a sandbox without rules, `blocked` with `rules` in the body is refused with `422 rules_immutable`. A request during a pause or a snapshot is refused with `409 operation_in_progress`. The new policy applies to every flow the sandbox already opened, not only new ones. A connection the new policy refuses stops carrying data in both directions, and the sandbox's socket sees no close, so the connection stalls. No restart is needed, and a later `PUT` with `public` restores reach. ## Outbound Address Outbound traffic leaves from the host's public address. The address is shared with other sandboxes on the host and is not fixed. --- ### Composition > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/composition.md A sandbox is composed from independent parts on its create request. Sandboxes also compose with each other, as the state of one becomes the source of the next. ## Parts Each part is set by its own field on the [create request](/docs/edge-compute/sandboxes/common-control-plane/creation), or by the matching flag of `telnyx-edge sandbox-cpu create`, and a part left out takes its default. The request below composes a 2 vCPU sandbox from the official Python image. It reaches only PyPI and OpenAI, and sends an OpenAI key that the sandbox never holds. It pauses after 5 idle minutes and terminates after an hour. ```json Request { "image": { "ref": "docker.io/library/python:3.12-slim" }, "cpu": 2, "memory_mib": 2048, "env": { "PYTHONUNBUFFERED": "1" }, "network": { "egress": "allowlist", "allow_out": ["pypi.org", "*.pythonhosted.org"], "rules": { "api.openai.com": { "headers": { "Authorization": "Bearer {{secrets.OPENAI_KEY}}" } } } }, "timeout": 3600, "idle_timeout": 300, "name": "research-agent" } ``` ### Source A create names exactly one source. | Field | Starts From | | --- | --- | | `image` | A fresh boot of an OCI image. `{"ref": "...", "registry_secret": "..."}`. See [Templates](/docs/edge-compute/sandboxes/organization-resources/templates#images). | | `template` | A template's ready state, by ID or name. See [Templates](/docs/edge-compute/sandboxes/organization-resources/templates#creating-a-sandbox-from-a-template). | | `from` | A snapshot's memory and disks. `{"snapshot": "snap-..."}`. See [Snapshots](/docs/edge-compute/sandboxes/common-control-plane/snapshots). | ### Size | Field | Default | Allowed | | --- | --- | --- | | `cpu` | `1` | `1` or `2` vCPU | | `memory_mib` | `1024` | `256` to `4096` | | `disk_gib` | `16` | `16`. The workspace disk, beside an 8 GiB root disk. | A size outside these values is refused with `422 resources_not_allowed`. A sandbox from a template or a snapshot takes its source's sizes. ### Main Command `command` is optional, and its presence changes how the sandbox ends. - **Without `command`**, the sandbox idles and serves [execs](/docs/edge-compute/sandboxes/data-plane-operations/execs) until it times out or is terminated. - **With `command`**, the command is the sandbox's main process. It runs once, when the sandbox first reaches `running`. Its exit terminates the sandbox with `termination_reason` `exited` and its `exit_code`. Its output is the sandbox's [logs](/docs/edge-compute/sandboxes/data-plane-operations/main-command#logs), and its stdin is reached through `GET /sandbox/{id}/attach`. ```json Request { "image": { "ref": "ghcr.io/acme/eval-runner:3" }, "command": ["python", "-m", "evals.run", "--suite", "smoke"], "workdir": "/workspace" } ``` See [Linux](/docs/edge-compute/sandboxes/linux#processes-and-users) for the user and directory the main command runs with. ### Environment | Field | Description | | --- | --- | | `env` | Variables for every process in the sandbox. Names match `[A-Za-z_][A-Za-z0-9_]*`. A `{{secrets.}}` marker becomes a [placeholder](/docs/edge-compute/sandboxes/organization-resources/secrets#placeholders). | | `workdir` | An absolute path. The main command's working directory, and the default for execs. | | `secrets_env`, `secrets_files` | Secret values delivered into the sandbox. See [Secrets](/docs/edge-compute/sandboxes/organization-resources/secrets#delivery-into-the-sandbox). | An invalid variable is refused with `422 invalid_env`. See [Linux](/docs/edge-compute/sandboxes/linux#environment-variables) for the order in which variables apply, and [Limits](/docs/edge-compute/sandboxes/platform/limits) for their sizes. ### Network `network` sets the outbound policy, the secret rules, and access to ports. | Field | Description | | --- | --- | | `network.egress` | `public` (default), `allowlist`, or `blocked`. See [Network Limits](/docs/edge-compute/sandboxes/common-control-plane/network-limits). | | `network.allow_out` | CIDRs and domains reachable under `allowlist`. | | `network.rules` | Headers the host adds to HTTPS requests. See [Secrets](/docs/edge-compute/sandboxes/organization-resources/secrets#secret-rules). | | `network.public_traffic` | `true` (default) or `false`. See [Ports](/docs/edge-compute/sandboxes/out-of-band-access/ports#access). | ### Lifetime `timeout`, `on_timeout`, `idle_timeout`, and `on_idle` set when the sandbox pauses or terminates on its own. See [Platform-Managed Lifecycle](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle). ### Name, Tags, and Region | Field | Description | | --- | --- | | `name` | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`. Unique among the organization's sandboxes that are not terminated, or the create is refused with `409 name_conflict`. | | `tags` | Up to 20 key-value pairs. Keys are 1 to 63 characters and values at most 255. | | `region` | The sandbox's region. See [Regions](/docs/edge-compute/sandboxes/platform-properties/regions). | ## Lineage Each arrow below is a request that turns one sandbox's source into the next. The diagram shows an OCI image built into a template or creating a sandbox directly, a template creating a sandbox, a running sandbox snapshotted with the snapshot creating new sandboxes, and a running sandbox forked into as many as 20 sandboxes. - **Image to template.** An image is booted once, its server started, and its ready state kept as a [template](/docs/edge-compute/sandboxes/organization-resources/templates). - **Template to sandbox.** A sandbox from a template resumes that ready state, with the server already listening. - **Sandbox to snapshot.** A [snapshot](/docs/edge-compute/sandboxes/common-control-plane/snapshots) keeps a running sandbox's memory and disks, and new sandboxes start from it. - **Sandbox to forks.** A [fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) copies a running sandbox into as many as 20 sandboxes at once, within the organization's sandbox quota, each with its live state. --- ### Linux > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/linux.md Every sandbox is a Linux virtual machine booted from an OCI image, never a container that shares the host's kernel. The image provides the userland. The platform provides the kernel, the first process, and the disks. ## Control Plane Support A Linux sandbox supports every operation of the common control plane, through the API or the `telnyx-edge` CLI. | Operation | Linux | | --- | --- | | [Create](/docs/edge-compute/sandboxes/common-control-plane/creation) | Yes, from a `linux/amd64` OCI image, a template, or a snapshot | | [Batch create](/docs/edge-compute/sandboxes/common-control-plane/creation#batch-create) | Yes, up to 10 sandboxes at once | | [List, read, and update](/docs/edge-compute/sandboxes/common-control-plane/operations) | Yes | | [Pause and resume](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#pause-and-resume) | Yes, with memory, processes, and disks kept | | [Connect](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#connect) | Yes | | [Terminate](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#terminate) | Yes | | [Wait](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#wait) | Yes | | [Fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) | Yes, up to 20 sandboxes with the source's live state | | [Snapshots](/docs/edge-compute/sandboxes/common-control-plane/snapshots) | Yes, of memory and disks | | [Templates](/docs/edge-compute/sandboxes/organization-resources/templates) | Yes, with a ready-state checkpoint | | [Timeout and idle timeout](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle) | Yes | | [Paused retention](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle#paused-retention) | 7 days | ## Virtual Machine | Component | Description | | --- | --- | | Kernel | A Linux kernel provided by Telnyx. It loads no modules. | | First process | A Telnyx init process, which runs execs, serves files, and supervises the main command. | | Root disk | `/`, ext4, 8 GiB, built from the image. | | Workspace disk | `/workspace`, ext4, 16 GiB. | | Network | One IPv4 interface. No IPv6. | | Architecture | x86-64. | A disk that fills returns `ENOSPC` to the writing process. The sandbox keeps running. ## Image Requirements - **Platform.** The image must offer `linux/amd64`. From a multi-platform index, the `linux/amd64` manifest is used. - **Layers.** Layers are gzip-compressed or plain tar. zstd and foreign layers are refused. - **Size.** The unpacked image must fit the 8 GiB root disk. - **Registry.** The reference names its registry host. See [Templates](/docs/edge-compute/sandboxes/organization-resources/templates#images). The build drops extended attributes, so file capabilities set in the image are lost. Device nodes and FIFOs in the image are not created. ## Processes and Users | Process | Runs As | Working Directory | | --- | --- | --- | | Main `command` | The image's `USER` | `workdir`, else the image's `WORKDIR` | | Exec | `root`, or the exec's `user` | The exec's `workdir`, else the sandbox's | | File requests | `root` | Not applicable | The image's `ENTRYPOINT` and `CMD` are never run. Root in a sandbox is root in its virtual machine only. ## Environment Variables Each process receives its environment in layers. A later layer replaces an earlier variable of the same name. 1. The platform defaults: `PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`, `HOME=/root`, `LANG=C.UTF-8`, and the certificate variables listed under [Secrets](/docs/edge-compute/sandboxes/organization-resources/secrets#trust), which point common clients at `/etc/ssl/certs/ca-certificates.crt`. 2. The image's `ENV`. 3. The create's `env`. 4. Secrets delivered by `secrets_env`. 5. An exec's own `env`, for that exec. The certificate variables are set with or without [secret rules](/docs/edge-compute/sandboxes/organization-resources/secrets#trust). ## Reserved | Reserved | Use | | --- | --- | | Port `49983` | Platform use. It is not reachable on a port URL. | | `/.telnyx` | Platform files. File requests cannot write, rename, or delete under it, whether or not it exists. | | `/run/sandbox-init/` | Platform state. | | `TELNYX_SANDBOX_*` | Variable names reserved for the platform. None is set in the sandbox, and a create or exec `env` with the prefix is refused with `422 invalid_env`. | ## Identity The sandbox's `/etc/machine-id` is written at its first boot. A sandbox created from a template, a snapshot, or a fork receives a new machine ID, new SSH host keys, and a reseeded random number generator before its code resumes. --- ### Isolation > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/isolation.md Sandboxes are isolated by default. Every sandbox is a separate virtual machine, and the platform treats all code in it as hostile. | Boundary | What Is Separated | Mechanisms | | --- | --- | --- | | Runtime | Processes, memory, kernel, devices, and disks | A separate virtual machine per sandbox, with hard CPU, memory, and disk limits | | Network | Traffic between a sandbox and the host, other sandboxes, private networks, and the internet | A separate network per sandbox, with a platform deny set and the sandbox's own egress mode | | Organization | Sandboxes, templates, snapshots, and secrets of different accounts | A token bound to one organization on every request | ## Runtime Isolation Each sandbox runs its own Linux kernel in its own virtual machine. Hardware virtualization, not a shared kernel, separates the sandbox from the host and from every other sandbox. Root inside the sandbox is root in that virtual machine only. The host also confines each virtual machine as an unprivileged process with access to its own sandbox's files only. CPU and memory are hard limits on the virtual machine. Disks are created at their full size. A sandbox that fills its workspace receives `ENOSPC`, and a request above the allowed sizes is refused, never reduced. See [Composition](/docs/edge-compute/sandboxes/composition#size). A clone, fork, or restore receives a new machine ID, new SSH host keys, and new entropy before user code resumes. Two sandboxes started from one snapshot never share an identity or a random number sequence. ## Network Isolation Outbound, inbound, and sandbox-to-sandbox traffic are controlled separately. | Direction | Default | Controls | | --- | --- | --- | | Outbound | The internet is reachable. Private ranges and the platform are not. | `network.egress`, `network.allow_out`, and [secret rules](/docs/edge-compute/sandboxes/organization-resources/secrets) | | Inbound | Any port is reachable on its port URL. | `network.public_traffic` and the traffic token. See [Ports](/docs/edge-compute/sandboxes/out-of-band-access/ports). | | Sandbox to sandbox | Blocked | None. Two sandboxes reach each other only through port URLs. | The platform deny set applies under every egress mode, and no `allow_out` entry overrides it. - `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16` - `169.254.0.0/16`, which includes cloud metadata addresses - `100.64.0.0/10` - The host's own public address TCP port 25 is blocked to every destination. The sandbox has no IPv6, and DNS resolves public names only. See [Network Limits](/docs/edge-compute/sandboxes/common-control-plane/network-limits) for the egress modes. ## Organization Isolation Every sandbox, template, and snapshot belongs to one organization. Every request carries an API key or a token for one organization. The control plane and the data plane both answer only with that organization's resources. A request from another organization receives `404` for a sandbox ID it does not own. A fork or a snapshot copies a sandbox's live state into sandboxes of the same organization only. Secrets stay outside the sandbox. A [secret rule](/docs/edge-compute/sandboxes/organization-resources/secrets) keeps the value on the host, which sets the header in outbound HTTPS requests to the hosts the rule names. A placeholder copied out of a sandbox resolves nowhere else. --- ### Persistence > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/persistence.md A sandbox keeps its disk for its whole life, and keeps its memory and processes while paused. Nothing of a sandbox is kept after it terminates, its snapshots included. | Layer | What Is Kept | Mechanisms | | --- | --- | --- | | Disk | The root disk and the workspace disk | Kept from create to terminate, through every pause | | Memory | Running processes, open files, sockets, and everything in RAM | Pause and resume, snapshots, forks | | Beyond a sandbox | A ready-to-run image with its server started | [Templates](/docs/edge-compute/sandboxes/organization-resources/templates) | ## Disk Persistence A sandbox has a root disk, built from its image, and a separate workspace disk. Both keep every write until the sandbox terminates. A pause, a resume, a snapshot, and a change to the network policy never discard disk contents. See [Linux](/docs/edge-compute/sandboxes/linux) for the paths and sizes. ## Memory Persistence A pause stops the sandbox's virtual machine and saves its full memory, device state, and disks. A resume restores all of it on the same host. Processes continue from the instruction where they stopped, and their open files and in-memory state are intact. - **Execs.** An exec that was running at the pause reads `interrupted` after the resume. Its process keeps running in the sandbox, but its output stream ends. Finished execs keep their output. See [Execs](/docs/edge-compute/sandboxes/data-plane-operations/execs). - **Network connections.** Sockets survive the pause inside the sandbox. A remote end may close a connection that stays silent for the length of the pause. - **Timeout.** The `timeout` clock stops while the sandbox is paused. A paused sandbox uses no CPU and does not count against the organization's [concurrency quota](/docs/edge-compute/sandboxes/platform-properties/scale#capacity). A resume takes the quota back, and a resume refused for quota leaves the sandbox paused. ## Copies of a Sandbox ### Snapshots A snapshot is a named copy of a running sandbox's memory and disks. The source keeps running while the snapshot is taken. A new sandbox created `from` a snapshot starts with the processes and files the source had at that moment. A snapshot is usable while its source exists, and is removed when the source terminates. See [Snapshots](/docs/edge-compute/sandboxes/common-control-plane/snapshots). ### Forks A fork creates one or more new sandboxes from a running sandbox's live state in one request. Each sibling is independent from its first instruction and outlives its source. The source keeps running. See [Fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork). ## Persistence Beyond a Sandbox A template is a named image that the platform boots once, starts, and checkpoints when it is ready. Every sandbox created from it resumes that checkpoint. A template exists until it is deleted, independently of every sandbox. See [Templates](/docs/edge-compute/sandboxes/organization-resources/templates). A snapshot published as a template Coming soon will keep a sandbox's live state after the sandbox terminates. ## Retention | Interval | Applies To | Default | Effect | | --- | --- | --- | --- | | `timeout` | A `running` sandbox | 300 seconds | `on_timeout`: `terminate` (default) or `pause` | | `idle_timeout` | A `running` sandbox with no activity | None | `on_idle`: `pause` (default) or `terminate` | | Paused retention | A `paused` sandbox | 7 days | Terminates with `termination_reason` `paused_expired` | | Lifecycle events | Every sandbox | 7 days | Events older than the retention are removed | The `timeout` clock counts only time spent running. [Common Control Plane](/docs/edge-compute/sandboxes/common-control-plane/platform-managed-lifecycle) explains activity, the timeout requests, and the minimum lifetime after a resume. ## Opting Out of Persistence A sandbox created with the default `timeout` and `on_timeout` terminates after 300 seconds of running and discards its state. A terminate request discards it at once. Terminated sandboxes keep no disk and are never resumable. --- ### Scale > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/scale.md Sandboxes are built to be created, forked, and discarded in large numbers. Each sandbox is sized when it is created, and a quota in each region bounds how many an organization runs at once. | Dimension | What Scales | Mechanisms | | --- | --- | --- | | Sandbox | The vCPU, memory, and disk of one sandbox | `cpu`, `memory_mib`, and `disk_gib` on the create, or a template's sizes | | Fleet | The number of sandboxes | Batch creates, templates, snapshots, and fork | | Workload | Processes inside one sandbox | Concurrent execs | ## Sandbox Scaling A sandbox's size is set at create and fixed for its life. A sandbox created from a template or a snapshot takes that source's size, because the size is part of the saved memory. A create that names a size beside a template is refused with `422 template_field_conflict`. See [Composition](/docs/edge-compute/sandboxes/composition#size) for the allowed sizes. ## Fleet Scaling A fleet is many independent sandboxes, typically one per user, task, or agent run. | Mechanism | Starting State | Use | | --- | --- | --- | | [Batch create](/docs/edge-compute/sandboxes/common-control-plane/creation#batch-create) | A fresh boot of an image, or a template's ready state | Many sandboxes of the same definition in one request | | [Template](/docs/edge-compute/sandboxes/organization-resources/templates) | The image booted, its start command run, and its ready check passed | A server or tool already listening when the sandbox reaches `running` | | [Snapshot](/docs/edge-compute/sandboxes/common-control-plane/snapshots) | A running sandbox's memory and disk at the moment of the snapshot | Many sandboxes from a prepared state while its source sandbox exists | | [Fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) | A running sandbox's memory and disk, now | Branching an agent's work into many attempts at once | A fork answers at once with every sibling in `starting`, then places each sibling as soon as the source's state is saved. The siblings share a `swarm` ID with their source, and a list request filters by it. Placement depends on available capacity and access to the saved state. Warm pools of started sandboxes Coming soon will hand out a template's sandboxes without a boot or a restore. ## Workload Concurrency A sandbox can run multiple execs concurrently, subject to its execution limits. Each exec is its own process with its own output stream, stdin, and exit code. A long task runs as one exec while the agent sends other execs beside it. See [Execs](/docs/edge-compute/sandboxes/data-plane-operations/execs). ## Capacity | Control | What It Limits | Scope | | --- | --- | --- | | Concurrency quota | Sandboxes that are `starting` or `running` | Organization, per region | | Per-sandbox sizes | vCPU, memory, and disk of one sandbox | Sandbox | | Snapshot cap | Named snapshots held by one sandbox | Sandbox | | Template cap | Templates held by one organization | Organization, per region | A paused or terminated sandbox does not count against the concurrency quota. A create, batch, or fork past the quota is refused whole with `429 quota_exceeded`. When no host has room, a create is refused with `503 no_capacity` and a `Retry-After` header. A batch item no host admits is an error entry in the batch response. A fork sibling no host can place reads `terminated` with `termination_reason` `no_capacity`. See [Limitations](/docs/edge-compute/sandboxes/limitations) for the values. ### Reclaiming Capacity - A `timeout` terminates or pauses a sandbox that runs too long. - An `idle_timeout` pauses or terminates a sandbox no client is using. - A paused sandbox frees its quota and keeps its state. ### Operating at Scale Every create and lifecycle request accepts an `Idempotency-Key` header. A retried request with the same key receives the first response and creates nothing new. [Lifecycle Events](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) reports every state change across all sandboxes from one cursor. --- ### Regions > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform-properties/regions.md A sandbox runs in one region for its whole life. Region names are the same as those of [Edge Compute functions](/docs/edge-compute/configuration). | Region | Location | Regional Sandbox API | | --- | --- | --- | | `us-east-1` | United States, East | `https://api.us-east-1.sandbox.telnyxcompute.com` | More regions are added as separate deployments. A client learns every region's base URL from the [token response](/docs/edge-compute/sandboxes/authentication#sandbox-token). ## Choosing a Region `region` on a create picks the region. Without it, the control plane sends the create to the default region. A region the control plane does not know is refused with `404` and the title `Sandbox region not found`. A create sent directly to a region's data plane with another region's name is refused with `422 wrong_region`. ```json Request { "region": "us-east-1", "image": { "ref": "docker.io/library/python:3.12-slim" } } ``` ## Region in IDs Every ID carries its region, so no lookup is needed to find a resource. | Resource | ID Format | | --- | --- | | Sandbox | `sb--` | | Template | `tpl--` | The control plane forwards each request to the data plane of the region in the ID, and returns its answer unchanged. A client holding a token sends it to that data plane directly. ## What Stays in a Region - **Sandboxes.** A sandbox never moves. A pause, a resume, a snapshot, and a fork all happen in its region. - **Snapshots and forks.** A sandbox created from a snapshot or a fork is in its source's region. - **Templates.** A template exists in the region where it was created. A template with the same name in another region is a separate template, created there. - **Quotas.** The concurrency quota and the template cap apply per organization and per region. ## Listing Across Regions `GET /v2/compute/sandbox` at the control plane asks every region at once and merges the results, newest first. A region that does not answer is named in `unavailable_regions`, and the response is still `200`. `?region=us-east-1` limits the list to one region, and an unknown region is refused with `404`. At a region's data plane, the list holds that region's sandboxes only. --- ### Overview > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources.md Organization resources belong to the organization, not to any one sandbox. Each one is an API resource beside the sandbox resource, not under a sandbox ID, and sandboxes use it. - `/v2/compute/sandbox` - `/{sandbox_id}` is one sandbox. Everything under it belongs to that sandbox. - [`/template`](/docs/edge-compute/sandboxes/organization-resources/templates) holds templates. A create names one as the sandbox's source. - [`/v2/compute/secrets`](/docs/edge-compute/sandboxes/organization-resources/secrets) holds the organization's secrets. Secret rules and secret delivery name a secret, and the sandbox never holds its value. An organization resource outlives the sandboxes that use it. A template keeps serving new creates after earlier sandboxes terminate, and a secret serves sandboxes and [Edge Compute functions](/docs/edge-compute/configuration/secrets) alike. --- ### Templates > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/templates.md A template is a named image that the platform boots once, starts, and checkpoints when it is ready. A sandbox created from the template resumes that checkpoint, with the template's server already listening, instead of booting. ## Images Every sandbox and template starts from an OCI image. - **Reference.** `image.ref` is an OCI image reference that names its registry, such as `docker.io/library/python:3.12-slim`, `ghcr.io/acme/agent:1.4`, or a digest. A reference without a registry host, such as `python:3.12-slim`, is refused with `422 registry_not_allowed`. - **Builds.** The first sandbox or template that names a reference builds it for the organization. The build resolves the reference to a digest and pins it. Later creates reuse the build. - **Init.** A Telnyx init process runs as the first process. The image's `ENTRYPOINT` and `CMD` are never run. The image's `USER`, `ENV`, and `WORKDIR` are the defaults. See [Linux](/docs/edge-compute/sandboxes/linux) for the image requirements and the environment the image runs in. ### Private Registries `image.registry_secret` names a [secret](/docs/edge-compute/sandboxes/organization-resources/secrets) whose value is the registry credential, in the form `user:token`. The platform reads it when a build starts and never returns it. ```json Request { "image": { "ref": "ghcr.io/acme/agent:1.4", "registry_secret": "GHCR_PULL" } } ``` A failed pull sets the template's `failure` to `image_pull_failed`, and a sandbox created from an image that cannot be pulled reads `terminated` with `termination_reason` `build_failed`. Nothing from the registry's response is returned. ## Creating a Template `POST /v2/compute/sandbox/template` creates a template and builds it. The response is `202` with the template in `building`. The CLI's `--wait` waits until the template is `ready` or `failed`, and prints its ID. ```bash Workstation telnyx-edge sandbox-cpu template create --name doc-web \ --image docker.io/library/python:3.12 \ --start-command 'python3 -m http.server 8000' \ --ready-command 'curl -fsS http://127.0.0.1:8000' \ --ready-timeout 60 \ --wait ``` ```json API { "name": "doc-web", "image": { "ref": "docker.io/library/python:3.12" }, "start_command": ["python3", "-m", "http.server", "8000"], "ready_command": ["curl", "-fsS", "http://127.0.0.1:8000"], "ready_timeout": 60 } ``` ```text Output Waiting for template tpl-us-east-2-01a1d753-25ef-74c5-9261-fcd1214236a3 to be ready... tpl-us-east-2-01a1d753-25ef-74c5-9261-fcd1214236a3 ``` The build above took 106 seconds. The CLI's `--start-command` and `--ready-command` each take one string, which runs as `sh -c ''`. | Field | Description | | --- | --- | | `name` | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `.`, `_`, and `-`, not starting with `tpl-`. Unique per organization and region. | | `image` | `ref` and an optional `registry_secret`, as on a sandbox create. | | `start_command` | Optional. The template's main process, as an array of strings. | | `ready_command` | Optional. A command run every second until it exits `0`. | | `ready_timeout` | Seconds to wait for `ready_command`. Default `60`, maximum `600`. A value outside 1 to 600, or one without a `ready_command`, is refused with `400`. | | `workdir`, `env` | The start command's working directory and environment. `env` cannot hold secret markers. | | `cpu`, `memory_mib`, `disk_gib` | The size of every sandbox created from the template. Defaults as on a sandbox create. | | `region` | The template's region. See [Regions](/docs/edge-compute/sandboxes/platform-properties/regions). | A name beginning with `tpl-` is refused with `400`, and a name already in use with `409 name_conflict`. An `env` value with a secret marker is refused with `422 template_env_secret`, because the environment is saved in the checkpoint's memory. Secrets go on each sandbox's create instead. ### Ready State The build runs in four steps. 1. The platform builds the image and boots it. 2. `start_command` starts as the template's main process, with `workdir` and `env`. 3. `ready_command` runs about 8 seconds after the start command, then every second until it exits `0`, for up to `ready_timeout` seconds. 4. The platform freezes the template's processes and checkpoints the template's memory and disks. Without a `start_command`, the checkpoint is taken as soon as the sandbox is up. Without a `ready_command`, it is taken one second after the start command starts. ### States | `state` | Meaning | | --- | --- | | `building` | The image or the checkpoint is being built. | | `ready` | Sandboxes can be created from the template. | | `failed` | The build failed. `failure` names the cause. | | `failure` | Cause | | --- | --- | | `image_pull_failed` | The image could not be pulled. | | `build_failed` | The image could not be built into a root disk. | | `start_failed` | `start_command` exited. | | `ready_timeout` | `ready_command` did not exit `0` within `ready_timeout`. | | `internal_error` | The platform failed. | A `ready_command` that never passes costs the full build before the template reads `failed` with `failure` `ready_timeout`. ## Creating a Sandbox from a Template `template` takes the template's ID or name, in place of `image`. ```bash Workstation telnyx-edge sandbox-cpu create --template doc-web \ --name doc-from-template \ --timeout 600 ``` ```json API { "template": "doc-web", "name": "doc-from-template", "timeout": 600 } ``` ```text Output Waiting for sandbox sb-us-east-2-01a1d754-c491-74da-9048-33efc8804ca8 to be running... sb-us-east-2-01a1d754-c491-74da-9048-33efc8804ca8 ``` The sandbox reaches `running` with the start command's process already serving. The create above took about 3 seconds. ```bash Workstation telnyx-edge sandbox-cpu exec doc-from-template \ -- curl -sS -o /dev/null -w '%{http_code}\n' \ http://127.0.0.1:8000 ``` ```text Output 200 ``` That process is the sandbox's main [`command`](/docs/edge-compute/sandboxes/composition#main-command). Its exit ends the sandbox, and its output is the sandbox's [logs](/docs/edge-compute/sandboxes/data-plane-operations/main-command#logs). Each sandbox receives a new machine identity and new entropy when it resumes. - `command`, `workdir`, `env`, `image`, `cpu`, `memory_mib`, and `disk_gib` are the template's. Any of them beside `template` is refused with `422 template_field_conflict`. - `network`, `timeout`, `on_timeout`, `idle_timeout`, `on_idle`, `name`, `tags`, `secrets_env`, `secrets_files`, and `region` apply per sandbox. - An unknown or deleted template is refused with `422 unknown_template`. A template not `ready` is refused with `409 template_not_ready`. ## Managing Templates | Request | Effect | | --- | --- | | `GET /sandbox/template` | Lists templates, filtered by `name`. The control plane lists every region's, and a region's data plane lists its own. | | `GET /sandbox/template/{id}` | Returns one template. | | `POST /sandbox/template/{id}/rebuild` | Pulls the image again, picking up a moved tag, and takes a new checkpoint. Returns the template to `building`. | | `DELETE /sandbox/template/{id}` | Deletes the template. Returns `204`. | A region's data plane also serves these requests for its own templates. `telnyx-edge sandbox-cpu template list`, `get`, `rebuild`, and `delete` send the same requests. **Rebuild.** Sandboxes already created keep running on the previous build. A create sent during the rebuild is refused with `409 template_not_ready`. A create accepted before the rebuild, whose sandbox has not started yet, starts on the new build. A rebuild while `building` is refused with `409 operation_in_progress`. **Delete.** The name is free at once and no new sandbox may name the template. Sandboxes created from it keep running. **Tags** Coming soon. A tag such as `doc-web:v2` will pin a create to one build, while a rebuild moves the untagged name. **Platform updates.** A checkpoint loads only on the platform build that took it. When the platform updates its hosts, it rebuilds affected templates automatically. The template reads `building` meanwhile. --- ### Secrets > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/organization-resources/secrets.md A secret rule lets code in a sandbox use a credential without the sandbox ever holding it. The host adds the value to outbound HTTPS requests on the sandbox's behalf. ## Storing Secrets Sandboxes use the same secrets as [Edge Compute functions](/docs/edge-compute/configuration/secrets). A secret is created, updated, and deleted with `telnyx-edge secrets` or at `https://api.telnyx.com/v2/compute/secrets`. Names are stored in upper case, so a secret created as `openai_key` is referenced as `OPENAI_KEY`. ```bash Shell telnyx-edge secrets add OPENAI_KEY "sk-..." ``` A value is used up to 64 KiB. ## Secret Rules `network.rules` on the create maps a host to the headers the platform sets on HTTPS requests to it. A header value is a template with `{{secrets.}}` markers. ```json Request { "image": { "ref": "docker.io/library/python:3.12-slim" }, "network": { "rules": { "api.openai.com": { "headers": { "Authorization": "Bearer {{secrets.OPENAI_KEY}}" } } } } } ``` Code in the sandbox sends a normal HTTPS request to `api.openai.com`. The host terminates TLS for that host, sets the `Authorization` header with the value, and forwards the request. The sandbox's code, environment, files, and snapshots never contain the value. ### Hosts - **Exact names.** `api.openai.com` matches that name only. - **Wildcards.** `*.example.com` matches every name below `example.com` at any depth, never `example.com` itself. - **Ports.** A rule applies to TLS on port 443 only. Plain HTTP and other ports receive no header. A rule's host is reachable under the `allowlist` egress mode without an `allow_out` entry. Rules are refused under `blocked` with `422 rules_not_allowed`. ### Headers - A rule's header replaces any header of the same name the sandbox sent. - Every marker in a header must resolve. Otherwise the platform omits the header, removes the sandbox's header of the same name, and still forwards the request. - `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`, and the hop-by-hop and `Proxy-*` headers cannot be set. - HTTP/1.1, HTTP/2, gRPC, and WebSocket requests all receive the header. A rule names at most 32 hosts with at most 16 headers each. A template is at most 2,048 bytes. Rules are fixed at create, and a [snapshot](/docs/edge-compute/sandboxes/common-control-plane/snapshots) or [fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) copies them. ### Validation Every secret a rule names must exist when the sandbox is created. A missing one is refused with `422 unknown_secret`. When the platform cannot read the organization's secrets, the create is refused with `503 secrets_unavailable` and a `Retry-After` header. ### Updates An updated value reaches a rule's headers within about a minute, with no restart. A deleted secret's header is omitted from then on. ## Trust A sandbox with rules receives its own certificate authority, limited to the rules' hosts. The sandbox trusts it from its first instruction. - **System bundle.** The CA is appended to `/etc/ssl/certs/ca-certificates.crt` and written to `/etc/ssl/certs/sandbox-egress-ca.pem`. - **Client variables.** Every sandbox's environment, with or without rules, points common clients at the bundle with `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `REQUESTS_CA_BUNDLE`, `PIP_CERT`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_SYSTEM_CA`, `NPM_CONFIG_CAFILE`, `GIT_SSL_CAINFO`, `AWS_CA_BUNDLE`, `CARGO_HTTP_CAINFO`, `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH`, `DENO_CERT`, and `BUN_CA_BUNDLE_PATH`. A client that pins the destination's certificate, or uses its own trust store such as a JVM keystore, fails the handshake to a rule host. Containers started inside the sandbox do not inherit the trust. ## Placeholders A `{{secrets.}}` marker in the create's `env`, or in an exec's `env`, becomes a placeholder, a random string that stands in for the value. It lets a client that refuses to start without the variable set run as usual. The host sets a rule's header from the rule itself, whatever the code sent, so no request needs the placeholder. A placeholder sent to any other host, or copied out of the sandbox, is a worthless string. ## Delivery into the Sandbox Some credentials cannot travel in an HTTPS header, such as a database password, an SSH key, or a client certificate. `secrets_env` and `secrets_files` deliver a secret's value into the sandbox. ```json Request { "image": { "ref": "docker.io/library/python:3.12-slim" }, "secrets_env": { "DATABASE_PASSWORD": "DB_PASSWORD" }, "secrets_files": { "/run/secrets/deploy_key": "DEPLOY_KEY" } } ``` | Field | Shape | Limits | | --- | --- | --- | | `secrets_env` | `{"": ""}` | 16 variables, names up to 128 bytes | | `secrets_files` | `{"/": ""}` | 16 files, paths up to 1,024 bytes | Delivered values total at most 128 KiB per sandbox. A delivered value is read when the sandbox is created and does not change when the secret is updated. A delivered value is in the sandbox's memory and disk. Every snapshot and fork of that sandbox contains it. --- ### Execs > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/execs.md An exec is a command run in a `running` sandbox, as its own process with its own output, stdin, and exit code. Execs are served by the data plane with a [token](/docs/edge-compute/sandboxes/authentication#sandbox-token), never by the control plane. ## Running a Command `POST /sandbox/{id}/exec` starts a command. The response is `201` with the exec in `starting` or `running`. The CLI's `exec` starts the command, streams its output, and exits with its exit code. ```bash Workstation telnyx-edge sandbox-cpu exec doc-run-42 \ --workdir /workspace \ --env DATA_PATH=/workspace/data.csv \ -- sh -c 'echo "$DATA_PATH $PWD"' ``` ```bash API curl -X POST "$DATA_API/$SANDBOX_ID/exec" \ -H "Authorization: Bearer $SANDBOX_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "command": ["sh", "-c", "echo \"$DATA_PATH $PWD\""], "workdir": "/workspace", "env": { "DATA_PATH": "/workspace/data.csv" } }' ``` ```text Output /workspace/data.csv /workspace ``` The CLI's exit status is the command's own. ```bash Workstation telnyx-edge sandbox-cpu exec doc-run-42 \ -- sh -c 'echo "cleaning 3 files"; exit 7' echo $? ``` ```text Output cleaning 3 files 7 ``` | Field | Default | Description | | --- | --- | --- | | `command` | Required | An array of 1 to 4,096 arguments of at most 131,071 bytes each, in a request body of at most 1 MiB. No shell is implied. Use `["bash", "-lc", "..."]` for shell syntax. | | `env` | None | Variables merged over the sandbox's environment, for this exec only. Rules as on the create. | | `workdir` | The sandbox's `workdir`, else the image's `WORKDIR`, else `/` | An absolute path. | | `timeout` | None | Seconds before the exec is ended. | | `user` | `root` | A user name or a numeric UID that exists in the image. An unknown user is refused with `422 unknown_user`. | | `pty` | None | Runs the command in a terminal. See [PTY](#pty). | Any number of execs run at once in one sandbox. A command that cannot start, such as a binary that is not on the image's `PATH` or a `workdir` that does not exist, is refused with `400 bad_request` and the error's text. No exec is created. A request body over 1 MiB is refused with `413 request_too_large`. ## Exec Object ```json Output { "data": { "id": "exec-0193c4e8-2c1d-7a4b-9e0f-6d8a2b4c6e10", "sandbox_id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d", "command": ["sh", "-c", "echo \"$DATA_PATH $PWD\""], "workdir": "/workspace", "timeout": 600, "user": null, "pty": null, "status": "exited", "exit_code": 0, "reason": null, "created_at": "2026-11-11T19:20:02Z", "finished_at": "2026-11-11T19:20:41Z" } } ``` | `status` | Meaning | | --- | --- | | `starting`, `running` | The process is starting or running. | | `exited` | The process exited. `exit_code` is its code, or `-1` when a signal ended it. | | `failed` | The platform failed to run the process. `reason` is `agent_error`. | | `terminated` | The exec was ended by its `timeout` or by the sandbox's termination. `reason` is `timeout` or `sandbox_terminated`. | | `interrupted` | The sandbox paused while the exec ran. The process continues in the sandbox, but this exec record no longer streams it. | ## Output `GET /sandbox/{id}/exec/{exec_id}/attach` upgrades to a WebSocket. The upgrade request carries the token in `Authorization`. `offset` starts the stream at a byte offset, and `0` replays from the beginning. ```bash API WS_API=${DATA_API/https/wss} websocat -H "Authorization: Bearer $SANDBOX_TOKEN" \ "$WS_API/$SANDBOX_ID/exec/$EXEC_ID/attach?offset=0" ``` Every message is a JSON text frame. Data is base64. ```json Output {"type":"output","stream":"stdout","data":"Q29sbGVjdGluZyBwYW5kYXMK","offset":0} {"type":"output","stream":"stderr","data":"V0FSTklORzogLi4uCg==","offset":20} {"type":"heartbeat"} {"type":"exit","status":"exited","exit_code":0,"reason":null} ``` ### Server Messages | `type` | Fields | Meaning | | --- | --- | --- | | `output` | `stream`, `data`, `offset` | Bytes from `stdout` or `stderr`. One offset counts both streams. | | `truncated` | `oldest_offset` | The requested offset is older than the guest still holds. The stream continues from `oldest_offset`. | | `heartbeat` | None | Sent every 30 seconds. An open attach counts as activity. | | `exit` | `status`, `exit_code`, `reason` | The exec ended. The server closes with code `1000`. | | `stdin_closed` | None | A stdin write was refused because stdin is closed. | | `error` | `error` | The server closes with `1008` for a client error or `1011` for a server error. | ### Client Messages | `type` | Fields | Meaning | | --- | --- | --- | | `stdin` | `data` | Bytes for the exec's stdin, base64, at most 64 KiB decoded. | | `stdin_eof` | None | End-of-file on stdin. | | `resize` | `rows`, `cols` | A new terminal size, for a [PTY](#pty) exec. | A message over 128 KiB closes the socket with `1009`, and an unknown type with `1008`. Disconnecting never ends the exec and never closes its stdin. A client reattaches with the last offset it received plus the length of that data. An error before the upgrade, such as `404` or `409 sandbox_paused`, is a plain HTTP response. `GET /sandbox/{id}/exec/{exec_id}?wait=10` waits up to 10 seconds for the exec to finish before returning it, for clients that only need the exit code. The guest keeps the last 8 MiB of each exec's output, for the 32 most recently finished execs. Output records stay readable until the sandbox terminates. ## Stdin Stdin is written over the exec's [attach WebSocket](#output). `POST /sandbox/{id}/exec/{exec_id}/stdin/close` sends end-of-file, and answers `202` with the exec, also once the exec has ended. Closing an attach never closes stdin and never ends the exec. A `stdin` message after stdin is closed receives `stdin_closed`. ## Signals `POST /sandbox/{id}/exec/{exec_id}/kill` sends a signal to the exec's process group. The response is `202` with the exec as it was before the signal, also once the exec has ended. ```json Request { "signal": "SIGTERM" } ``` `signal` is one of `SIGTERM`, `SIGKILL` (default), `SIGINT`, `SIGHUP`, `SIGQUIT`, `SIGUSR1`, and `SIGUSR2`. Another name is refused with `400`. ## PTY A PTY exec runs a command in a terminal, for shells, editors, REPLs, and programs that behave differently without one. It is an ordinary exec with a `pty` object. The request below starts a login shell in a terminal of 40 rows and 120 columns. ```json Request { "command": ["bash", "-l"], "pty": { "rows": 40, "cols": 120, "term": "xterm-256color" } } ``` | Field | Description | | --- | --- | | `pty.rows`, `pty.cols` | The terminal size, each 1 to 65,535. | | `pty.term` | The `TERM` value, at most 64 bytes. Default `xterm-256color`. | A PTY merges stdout and stderr into one stream, as a terminal does. Its output arrives as `output` messages with `stream` `stdout`. The exec's [attach WebSocket](#output) carries keystrokes and screen output. - **Input.** Each keystroke or pasted block is a `stdin` message, base64. - **Output.** Screen output, including escape sequences, arrives as `output` messages. - **Resize.** A `resize` message changes the terminal size. ```json Client Messages {"type":"stdin","data":"bHMgLWxhCg=="} {"type":"resize","rows":50,"cols":160} ``` A `resize` on an exec without `pty` is refused. Disconnecting leaves the shell running, and a new attach resumes from any offset the guest still holds. The shell ends when its process exits, for example after `exit` is written to stdin. A [kill](#signals) with `SIGHUP` ends it as a closed terminal would. ## List `GET /sandbox/{id}/exec` lists the sandbox's execs, newest first, 20 per page and at most 100. `status` filters, and repeats. ## Execs and Pauses Execs keep their records across a pause. After a resume, finished execs show their output and exit codes. An exec that was running at the pause reads `interrupted`. Its process keeps running in the sandbox, and a kill or a stdin close on the `interrupted` record answers `202` with the record. An attach that is open when the sandbox pauses keeps receiving heartbeats and is not told. A new attach after the resume receives `exit` with status `interrupted`. Exec requests to a paused sandbox are refused with `409 sandbox_paused`. Send `connect` first. --- ### Main Command > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/main-command.md A sandbox created with a [`command`](/docs/edge-compute/sandboxes/composition#main-command) runs one more process, its main command, which is not an exec. Its stdin, its exit, and its logs have their own routes on the data plane. ## Attach `GET /sandbox/{id}/attach` is a WebSocket to the main command's stdin. Stdin goes in over it as `stdin` messages, as on an [exec's attach](/docs/edge-compute/sandboxes/data-plane-operations/execs#client-messages). The socket carries no output, so it is silent until its first `heartbeat` at 30 seconds. Its final message carries the exit code, and is sent again to a later attach. Output is read through the [logs](#logs). ## Stdin `POST /sandbox/{id}/stdin/close` sends end-of-file to the main command's stdin. `/attach` and `/stdin/close` are refused with `409 no_command` on a sandbox without a main command. ## Logs `GET /sandbox/{id}/logs` returns the main command's output as lines, oldest first, 20 per page and at most 100. ```json Output { "data": [ { "type": "line", "ts": "2026-11-11T19:04:06.120Z", "line": "Listening on :3000", "position": "1", ... } ], "meta": { "next_page_after": "1", "page_size": 20 } } ``` `page[after]` continues from a `position`. A sandbox without a main command has no log lines. `stream` is `null` on every line, and `?stream=` is refused with `400`, because the main command's output does not tell stdout and stderr apart. ### Follow `?follow=true` streams new lines as server-sent events. Each line is an `event: log` whose `id` is its position. A `Last-Event-ID` header resumes after that position. On a line that `follow=true` replays, `ts` is the time of the read. A comment is sent every 30 seconds, and an `event: end` marks the end of the logs once the sandbox has terminated. ```bash API curl -N "$DATA_API/$SANDBOX_ID/logs?follow=true" \ -H "Authorization: Bearer $SANDBOX_TOKEN" ``` ```text Output event: log id: 1 data: {"type":"line","ts":"2026-11-11T19:04:06.120Z","line":"Listening on :3000","position":"1"} ``` The host keeps 64 MiB of logs per sandbox. A line longer than 256 KiB is split. --- ### Files > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/files.md File routes read and write a `running` sandbox's filesystem directly, without an exec. They are served by the data plane with a [token](/docs/edge-compute/sandboxes/authentication#sandbox-token), never by the control plane. Every route takes the file's absolute path in `?path=`. ## Writing `PUT /sandbox/{id}/files?path=` writes the request body as the file's contents. Missing parent directories are created. The response is `201` for a new file and `200` for a replaced one. The CLI's `cp` copies one regular file, and a sandbox path ending in `/` takes the local file's name. ```bash Workstation telnyx-edge sandbox-cpu cp ./data.csv doc-run-42:/workspace/ ``` ```bash API curl -X PUT \ "$DATA_API/$SANDBOX_ID/files?path=/workspace/data.csv" \ -H "Authorization: Bearer $SANDBOX_TOKEN" \ -H "Content-Type: application/octet-stream" \ --data-binary @data.csv ``` ```text Output Copied 19 bytes to sb-us-east-2-01a1d753-025a-75a9-b353-ee17f60f17e3:/workspace/data.csv ``` The replace is atomic. A reader sees the old file or the new one, never a partial write, and an existing file keeps its mode and owner. `?directory=true` with no body creates a directory. ## Reading `GET /sandbox/{id}/files?path=` returns the file's bytes as `application/octet-stream`, with its `Content-Length`. `HEAD` returns the headers only. With the CLI, a local directory takes the sandbox file's name, and `-` writes the file to stdout. ```bash Workstation telnyx-edge sandbox-cpu cp doc-run-42:/workspace/report.json . ``` ```bash API curl "$DATA_API/$SANDBOX_ID/files?path=/workspace/report.json" \ -H "Authorization: Bearer $SANDBOX_TOKEN" -o report.json ``` ```text Output Copied 12 bytes from sb-us-east-2-01a1d753-025a-75a9-b353-ee17f60f17e3:/workspace/report.json to report.json ``` A transfer interrupted midway can retain status `200` while the body is shorter than `Content-Length`. Compare the received byte count with `Content-Length` and reject a mismatch, even if the HTTP library reports a clean end of stream. Discard an incomplete download and retry the whole request. A `Range` header is ignored, and the whole file is returned. ## Listing `?list=true` returns a directory's entries, 20 per page and at most 100. `?stat=true` returns the entry of the path itself. A symbolic link is reported as a link, not followed. ```json Output { "data": { "path": "/workspace/report.json", "name": "report.json", "type": "file", "size_bytes": 18234, "modified_at": "2026-11-11T19:21:07Z", "mode": 420, "uid": 0, "gid": 0 } } ``` | Field | Description | | --- | --- | | `type` | `file`, `directory`, `symlink`, or `other`. | | `mode` | The permission bits, including setuid, setgid, and sticky, as a decimal integer. `420` is `0644`. | | `uid`, `gid` | The numeric owner and group. | ## Renaming and Deleting `POST /sandbox/{id}/files/rename` renames a path. The response is `204`. ```json Request { "from": "/workspace/draft.md", "to": "/workspace/final.md" } ``` The target's parent must exist. A rename across filesystems, such as from `/` to `/workspace`, is refused with `409 cross_device`. `DELETE /sandbox/{id}/files?path=` deletes a file or an empty directory. The response is `204`. `?recursive=true` deletes a directory and its contents. A non-empty directory without it is refused with `409 directory_not_empty`. ## Sizes | Limit | Value | | --- | --- | | File size | 512 MiB. The request's `Content-Length` is checked before the body is read, and a larger write is refused with `413 file_too_large`. | | Streaming | Files over 8 MiB are streamed without buffering the whole file. Uploads use 8 MiB chunks; downloads are read internally in 1 MiB pieces and returned as one continuous response, not client-addressable HTTP ranges. | | Progress | An upload's first byte within 60 seconds, then each 8 MiB chunk within 5 minutes; each 1 MiB download piece must be consumed within 5 minutes. Missing a download deadline ends the response early: apply the byte-count check above. | | Concurrent transfers over 8 MiB | 4 per organization and 32 total on each API replica, shared by uploads and downloads. These are per-replica limits, not site-wide limits. Either limit can cause `503`, even below your organization's limit if the replica is full; honor `Retry-After` before retrying. | An `Idempotency-Key` on a `PUT` is accepted for bodies up to 8 MiB. A larger upload that carries one is refused with `400`. ## Paths - **Format.** Absolute, at most 4,096 bytes of UTF-8, not ending in `.` or `..`. An invalid path is refused with `422 invalid_path`. - **Missing.** A path that does not exist is `404`. - **Kind.** A write on a directory, or a directory write on a file, is refused with `409 path_type_mismatch`. A read, a `HEAD`, or `?list=true` on the wrong kind of path is refused with `422 invalid_path`. - **Reserved.** Writes, renames, and deletes under `/.telnyx` are refused with `422 invalid_path`, whether or not the directory exists. - **Owner.** File requests run as `root`. Every file request counts as activity for `idle_timeout`. File requests to a paused sandbox are refused with `409 sandbox_paused`. --- ### Metrics > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/metrics.md Metrics report a sandbox's CPU, memory, network, and disk usage by minute. `GET /sandbox/{id}/metrics` returns them at a 60-second step. It is served by the data plane with a [token](/docs/edge-compute/sandboxes/authentication#sandbox-token), never by the control plane. ```bash API curl -G "$DATA_API/$SANDBOX_ID/metrics" \ --data-urlencode "from=2026-11-11T19:00:00Z" \ --data-urlencode "to=2026-11-11T19:30:00Z" \ -H "Authorization: Bearer $SANDBOX_TOKEN" ``` | Parameter | Description | | --- | --- | | `from`, `to` | RFC 3339 times. The default window is the last 60 minutes. A window over 24 hours is refused with `400 bad_request`. | ```json Output { "data": { "sandbox_id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d", "from": "2026-11-11T19:00:00Z", "to": "2026-11-11T19:30:00Z", "step_seconds": 60, "latest": { "ts": "2026-11-11T19:29:50Z", "cpu_cores": 0.84, "mem_bytes": 612368384, "net_rx_bytes": 48213004, "net_tx_bytes": 1902334, "disk_bytes": 734003200 }, "series": [ { "ts": "2026-11-11T19:00:00Z", "cpu_cores_avg": 0.12, "cpu_cores_max": 0.97, "mem_bytes_avg": 401604608, "mem_bytes_max": 455081984, "net_rx_bytes": 1048576, "net_tx_bytes": 65536, "disk_bytes": 524288000 }, ... ] } } ``` | Metric | Description | | --- | --- | | `cpu_cores` | vCPU in use. `1.0` is one full vCPU. | | `mem_bytes` | The sandbox's memory use, measured on the host. | | `net_rx_bytes`, `net_tx_bytes` | Bytes received and sent on the sandbox's network interface during the interval, not since the start. | | `disk_bytes` | Bytes allocated on the workspace disk. | `latest` is the most recent sample, or `null` when there is none. Each `series` point summarizes one 60-second interval. The series covers the sandbox's current run. It restarts at a resume, and samples from before a pause are not served. For a `paused` or `terminated` sandbox, `latest` is `null` and `series` is empty. --- ### Lifecycle Events > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events.md A lifecycle event is recorded for every state change of a sandbox, as the change is made. Events are kept for 7 days and served by the data plane with a [token](/docs/edge-compute/sandboxes/authentication#sandbox-token), never by the control plane. ## Read Events | Request | Returns | | --- | --- | | `GET /sandbox/{id}/lifecycle_event` | One sandbox's events. | | `GET /sandbox/lifecycle_event` | The organization's events in the region, across all sandboxes. | | Parameter | Description | | --- | --- | | `since` | An RFC 3339 time. Events at or after it. Organization route only. | | `type` | One event type. Repeats for up to 8 types. | | `sandbox` | One sandbox ID. Organization route only. | | `page[size]` | Events per page. Default and maximum `100`. | | `page[after]` | The `next_page_after` cursor of the previous page. | ```bash API curl -G "$DATA_API/lifecycle_event" \ --data-urlencode "since=2026-11-11T19:00:00Z" \ --data-urlencode "type=terminated" \ -H "Authorization: Bearer $SANDBOX_TOKEN" ``` ```json Output { "data": [ { "id": "evt-0193c4f0-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "ts": "2026-11-11T19:34:05.218Z", "type": "terminated", "sandbox_id": "sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d", "data": { "reason": "timeout" } } ], "meta": { "next_page_after": "MjAyNi0xMS0xMVQxOTozNDowNVo...", "page_size": 100 } } ``` Events are ordered by `ts`, then `id`. Two changes committed close together can appear in either order, so an event with an earlier `ts` can follow one already read. Every event has a unique `id`. A client that polls for new events therefore reads again from a `since` a few seconds before the last event it holds, and drops the events whose `id` it already has. ## Event Types | `type` | `data` | | --- | --- | | `created` | `{}`, or `{"template": ...}`, `{"from_snapshot": ...}`, or `{"fork_of": ..., "swarm": ...}` for the source it started from | | `started` | `{}` | | `paused` | `{"reason": ...}`: `customer`, `idle_timeout`, or `timeout` | | `resumed` | `{}` | | `snapshotted` | `{"snapshot_id": ..., "name": ...}` | | `forked` | `{"swarm": ..., "count": ..., "sandbox_ids": [...]}` | | `network_updated` | `{"egress": ...}` | | `terminated` | `{"reason": ..., "exit_code": ...}`, with a [termination reason](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#terminate) | An unknown type, more than 8 types, or a malformed `since` or cursor is refused with `400`. A sandbox ID of another organization is `404` on the sandbox route and an empty page on the organization route. ## Webhooks Webhooks Coming soon will deliver the same events to an HTTPS endpoint as they happen. --- ### Ports > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/out-of-band-access/ports.md Every TCP port a process in a sandbox listens on has its own public URL for HTTP and WebSocket traffic. ```text https://-..sandbox.telnyxcompute.com ``` No port is declared in advance. A server that starts listening on port `3000` in sandbox `sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d` is reachable at once on `https://sb-us-east-1-0193c4d2-7f1a-7c2e-9d4b-5a6e8f0c1b2d-3000.us-east-1.sandbox.telnyxcompute.com`. ## Requests - **Protocols.** HTTP and WebSocket. TLS ends at the platform, and the server in the sandbox receives plain HTTP/1.1. A client may negotiate HTTP/2 with the platform, and the sandbox still receives HTTP/1.1. - **Path and body.** The path, query, and body reach the server unchanged. - **Headers.** The platform adds `X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, `X-Real-Ip`, and `X-Request-Id`, and sends each request with `Connection: close`. The other headers reach the server as sent, apart from the traffic token. - **Host.** The server receives the public host name in the `Host` header, so absolute links, redirects, and cookies work at the root path. - **Origin.** Each port is its own browser origin. Port `49983` is reserved for the platform and refused with `403 port_refused`. ## Access `network.public_traffic` on the create controls access to every port of the sandbox. It is fixed at create. | `public_traffic` | Access | | --- | --- | | `true` (default) | Anyone with the URL reaches the port. The sandbox ID is the only secret in the URL. | | `false` | A request must carry the sandbox's `traffic_token` in the `Telnyx-Sandbox-Traffic-Token` header. A request without it receives `403 traffic_token_required`. | The sandbox object returns `traffic_token` when `public_traffic` is `false`. The platform removes the header before the request reaches the sandbox. A fork receives its own traffic token. ```bash Shell curl https://$SANDBOX_ID-3000.us-east-1.sandbox.telnyxcompute.com/health \ -H "Telnyx-Sandbox-Traffic-Token: $TRAFFIC_TOKEN" ``` ## States A port answers only while its sandbox is `running`. | Condition | Response | | --- | --- | | The sandbox is `starting`, `paused`, or `terminated` | `502 sandbox_not_running` | | Nothing listens on the port | `502 port_closed` | | The sandbox does not answer the connection to the port | `502 port_unreachable` | | More than 256 connections are open to the sandbox, across all its ports | `503 too_many_connections` | Every refused request carries the error's title in a `Telnyx-Sandbox-Error` response header. See [Errors](/docs/edge-compute/sandboxes/platform/errors#port-errors). Traffic does not resume a paused sandbox. Send `connect` or `resume` first. See [Common Control Plane](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#pause-and-resume). ## Cookies `telnyxcompute.com` is shared by every sandbox and every Edge Compute function. A cookie that a page in one sandbox sets for a parent domain reaches every other sandbox and function under that domain. A cookie set without a `Domain` attribute stays on its port's host name. --- ### Limits > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform/limits.md This page lists the product's limits, per sandbox and per request. A request past a limit is refused with the error named here, never silently reduced. Additional quotas and size constraints are listed under [Limitations](/docs/edge-compute/sandboxes/limitations). ## Sandbox | Limit | Value | | --- | --- | | `timeout` | Default 300 seconds, or none | | Minimum lifetime after a resume | 300 seconds | | Paused retention | 7 days | | Environment | 256 variables, 32 KiB per value, 256 KiB in total | | Tags | 20 per sandbox | | Readable after termination | At least 30 days | ## Requests | Limit | Value | | --- | --- | | Request body, except file writes | 1 MiB, then `413 request_too_large` | | File size | 512 MiB, checked on the request's `Content-Length` before the body is read, then `413 file_too_large` | | Batch `count` | 1 to 10 | | Fork `count` | 1 to 20 | | List page size | Default 20, maximum 100 | | Lifecycle event page size | Default and maximum 100 | | `wait` and exec long polls | 10 seconds | | Token lifetime | 1 hour | | `Idempotency-Key` | 1 to 255 characters, kept 24 hours | ## Execs and Output | Limit | Value | | --- | --- | | Exec arguments | 4,096, each at most 131,071 bytes | | Exec output kept in the guest | The last 8 MiB per exec, for the 32 most recently finished execs | | Attach messages | 64 KiB of stdin per message, 128 KiB per message | | Main command logs | 64 MiB per sandbox. Lines over 256 KiB are split. | | Metrics window | 24 hours per request, at a 60-second step | | Lifecycle events | Kept 7 days | ## Network and Secrets | Limit | Value | | --- | --- | | `allow_out` entries | 256 | | Secret rule hosts | 32 per sandbox, 16 headers each | | Header template | 2,048 bytes | | Secret value | 64 KiB | | Delivered secrets | 16 variables and 16 files, 128 KiB in total | | Concurrent connections to rule hosts and domain entries | 256 per sandbox | | Concurrent connections to a sandbox's ports | 256 per sandbox, then `503` | | Outbound TCP port 25 | Blocked | ## Idempotency `Idempotency-Key` is accepted on every write: creates, batches, lifecycle requests, snapshots, forks, network changes, template requests, execs, kills, stdin closes, file writes up to 8 MiB, file deletes, and renames. - **Replay.** A repeat with the same key and the same request receives the first response, byte for byte, with its status. - **Reuse.** The same key with a different request is refused with `422 idempotency_key_reused`. - **In flight.** A repeat while the first request is still running is refused with `409 request_in_progress`. - **Failures.** A request that fails stores nothing, so its retry is evaluated again. A key is scoped to the organization, HTTP method, and endpoint path. Control-plane requests forwarded to the same regional endpoint and direct data-plane requests share the same idempotency scope; the plane itself is not part of the key. Repeating the same method and path with the same key and request replays the first response, while changing the query or request body returns `422 idempotency_key_reused`. The request body is compared byte for byte, so a reordered JSON body is a different request. --- ### Billing > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform/billing.md Sandbox resource usage depends on the [resources you configure](/docs/edge-compute/sandboxes/composition#size) and the sandbox's [lifecycle state](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#states). ## Resource Lifecycle | State | Resource behavior | | --- | --- | | `starting` | The sandbox is being provisioned. | | `running` | Its configured CPU, memory, and disks are available. | | `paused` | CPU execution stops; memory, processes, and disk state are preserved for resume. | | `terminated` | The sandbox is removed. | A [fork](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#fork) creates another sandbox with its own lifecycle. [Snapshots](/docs/edge-compute/sandboxes/common-control-plane/snapshots) preserve a sandbox's state, while [templates](/docs/edge-compute/sandboxes/organization-resources/templates) provide reusable starting points. ## Account Agent Sandboxes belongs to the organization's Telnyx account. Account balance, payment methods, and invoices are managed alongside other Telnyx services. You can read the account balance through the [Balance API](/api-reference/billing/get-user-balance-details) and view account-level charges through the [charges summary](/api-reference/get-monthly-charges-summary). ## Resource Usage [Lifecycle events](/docs/edge-compute/sandboxes/data-plane-operations/lifecycle-events) show when a sandbox changes state. [Metrics](/docs/edge-compute/sandboxes/data-plane-operations/metrics) report CPU, memory, and disk usage. Use these with the sandbox's configured resources to understand its activity. ## Resource Cleanup [Terminate a sandbox](/docs/edge-compute/sandboxes/common-control-plane/user-controlled-lifecycle#terminate) when it is no longer needed. Termination removes the sandbox and its snapshots. Templates are managed separately and remain available until deleted. --- ### Errors > Source: https://developers.telnyx.com/docs/edge-compute/sandboxes/platform/errors.md Every error the Agent Sandboxes API returns has an HTTP status and a code. Errors use the Telnyx error envelope. `title` is the error's name, and `source` points at the field or parameter at fault. ```json Output { "errors": [ { "code": "90001", "title": "resources_not_allowed", "detail": "memory_mib 8192 is above the largest size, 4096", "source": { "pointer": "/memory_mib" } } ] } ``` A `503` carries a `Retry-After` header. ## Sandbox Errors | Status | Code | Title | Cause | | --- | --- | --- | --- | | 401 | `90029` | `invalid_token` | The token is missing, expired, or not valid. | | 403 | `90030` | `invalid_identity` | The token carries no usable organization. | | 409 | `90010` | `name_conflict` | A live sandbox or template already has the name. | | 409 | `90011` | `request_in_progress` | A request with the same `Idempotency-Key` is still running. | | 409 | `90012` | `sandbox_not_running` | The operation needs a `running` sandbox. | | 409 | `90013` | `exec_not_running` | The exec has ended. | | 409 | `90014` | `path_type_mismatch` | The path is a directory where a file was expected, or the reverse. | | 409 | `90015` | `directory_not_empty` | The directory has contents and `recursive` was not set. | | 409 | `90021` | `operation_in_progress` | A pause, a snapshot, or a template build is in progress. | | 409 | `90022` | `snapshot_not_published` | The snapshot is not yet usable. | | 409 | `90025` | `source_terminated` | The snapshot's source sandbox has terminated. | | 409 | `90032` | `sandbox_paused` | Execs and files need a running sandbox. Send `connect`. | | 409 | `90033` | `invalid_state` | The sandbox's state does not allow the operation. | | 409 | `90035` | `cross_device` | A rename crosses filesystems. | | 409 | `90037` | `no_command` | The sandbox has no main command. | | 409 | `90039` | `sandbox_terminated` | The sandbox has terminated. | | 409 | `90040` | `snapshot_quota` | The sandbox already holds three snapshots. | | 409 | `90043` | `template_not_ready` | The template is not `ready`. | | 410 | `90046` | `logs_expired` | The sandbox's logs are no longer kept. | | 413 | `90016` | `file_too_large` | The file is over 512 MiB. | | 422 | `90001` | `resources_not_allowed` | A size is outside the allowed values. | | 422 | `90002` | `registry_not_allowed` | The image reference does not name a public registry host. | | 422 | `90003` | `invalid_env` | An environment variable is invalid or too large. | | 422 | `90004` | `invalid_workdir` | `workdir` is not an absolute path. | | 422 | `90005` | `invalid_command` | The command is empty or too large. | | 422 | `90006` | `invalid_path` | The file path is invalid or reserved. | | 422 | `90007` | `cidr_not_allowed` | An `allow_out` entry overlaps the deny set. | | 422 | `90009` | `idempotency_key_reused` | The `Idempotency-Key` was used for a different request. | | 422 | `90026` | `invalid_egress_rule` | A secret rule's host, header, or template is invalid. | | 422 | `90027` | `unknown_secret` | A named secret does not exist. | | 422 | `90028` | `rules_not_allowed` | Secret rules are not allowed under `blocked`. | | 422 | `90031` | `wrong_region` | `region` names another region than the API's. | | 422 | `90034` | `unknown_user` | The exec's `user` does not exist in the image. | | 422 | `90036` | `allow_out_not_allowed` | `allow_out` is set without `allowlist`. | | 422 | `90038` | `rules_immutable` | A network change alters `rules`. | | 422 | `90041` | `template_field_conflict` | A field is set beside `template` that the template defines. | | 422 | `90042` | `unknown_template` | The template does not exist or was deleted. | | 422 | `90044` | `template_env_secret` | A template's `env` holds a secret marker. | | 429 | `90017` | `quota_exceeded` | The organization is at its sandbox or template quota. | | 500 | `90020` | `internal_error` | The platform failed. | | 503 | `90019` | `no_capacity` | No host in the region has room. | | 503 | `90045` | `secrets_unavailable` | The organization's secrets could not be read. | ## Port Errors A request to a [port URL](/docs/edge-compute/sandboxes/out-of-band-access/ports) that the platform refuses carries the error in its body and the error's title in a `Telnyx-Sandbox-Error` response header. | Status | Code | Title | Cause | | --- | --- | --- | --- | | 403 | `90049` | `port_refused` | The port is `49983`, which the platform reserves. | | 403 | `90050` | `traffic_token_required` | The sandbox's ports are not public, and the request carries no valid `Telnyx-Sandbox-Traffic-Token`. | | 502 | `90047` | `port_closed` | Nothing in the sandbox listens on the port. | | 502 | `90048` | `port_unreachable` | The sandbox did not answer the connection to the port. | | 503 | `90051` | `too_many_connections` | More than 256 connections are open to the sandbox's ports. | A port on a sandbox that is not `running` answers `502` with the `sandbox_not_running` body. ## General Errors | Status | Code | Title | Cause | | --- | --- | --- | --- | | 400 | `10004` | `missing_parameter` | A required field is missing. | | 400 | `10015` | `bad_request` | The request is malformed, or names an unknown field. | | 400 | `10025` | `invalid_string_length` | A string is too short or too long. | | 400 | `10026` | `invalid_type` | A field has the wrong type. | | 404 | `10005` | `not_found` | The resource does not exist or belongs to another organization. | | 405 | `10015` | `method_not_allowed` | The route does not accept the method. | | 413 | `10015` | `request_too_large` | The request body is over 1 MiB. | | 429 | `10011` | Too many requests | The API key sent more than 20 requests to the control plane in one second. | | 503 | `10037` | `service_unavailable` | The sandbox is briefly unreachable, or a transfer limit was reached. | Unknown fields are refused, never ignored. The control plane limits each API key to 20 requests per second. A refused request carries the `ratelimit-limit`, `ratelimit-remaining`, and `ratelimit-reset` headers and no `Retry-After`. ## Control Plane Forwarding | Status | Cause | | --- | --- | | 404 | The sandbox or template ID names a region that does not exist. | | 404 | `region` on a create, or `?region=` on a list, names a region that does not exist. The body carries code `10005` and the title `Sandbox region not found`. | | 502 | The data plane of the sandbox's region did not answer. The control plane does not retry. | ---