Configuration

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

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

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

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

Constraints, enforced at ship time: binding and type must be identifiers and must not contain __; type is capped at 32 characters and may not start with telnyx (any case), which is reserved for platform-managed actors; binding names must be unique across all bindings in the file, and SECRETS is reserved as a binding name when the file has a [[secrets]] block. Multiple [[actors]] blocks are allowed — including two bindings pointing at the same type, as long as they declare the same env_vars.

Environment variables

An actor type’s environment is [env_vars.shared], then [env_vars.actor], then its own [[actors]] env_vars — a later layer wins on a key collision. Keys written directly under [env_vars] reach the function, not actors.

[env_vars.shared]
REGION = "us-east"              # the function and every actor type

[env_vars.actor]
LOG_LEVEL = "warn"              # every actor type

[[actors]]
binding  = "ACCOUNT"
type     = "Account"
env_vars = { LOG_LEVEL = "debug" }   # Account only — overrides [env_vars.actor]

Reserved names, the 50-variable cap per actor type, and how to test with telnyx-edge dev are covered in Environment variables. Secrets don’t go here: read them through a [[secrets]] binding and env.SECRETS.

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

Overview

Get Started

Concepts

Reference

Guides

Observability

For AI Agents

Environment variables

​Environment variables

​Related

Environment variables

Related