> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Run a Stateful Actor project locally with telnyx-edge dev — a full function + actor stack in Docker where env.<BINDING> calls resolve and actor state survives hot reloads.

A plain Edge Compute function is an ordinary program you run and `curl` directly — the [Functions local-dev guide](/docs/edge-compute/development) covers that. A Stateful Actor project is different: the `fetch` handler reaches its actors through an `env.<BINDING>` call, and that binding resolves only against a running actor runtime. There is no in-process emulation to fall back on.

`telnyx-edge dev` supplies the missing runtime. It generates the actor stack your project needs, boots it in Docker, serves your `fetch` handler on a local port, and hot-reloads on save — so `env.<BINDING>` calls hit real actors before you ship.

`telnyx-edge dev` is a development command; it does not deploy anything. When it works locally, ship with [`telnyx-edge ship`](/docs/edge-compute/deploy).

## Prerequisites

* **Docker**, running. The stack is a set of containers booted with `docker compose`.
* **A `telnyx.toml` umbrella project** — the two-export shape from [Project structure](/docs/edge-compute/stateful-actors/guides/project-structure): one module that exports an actor class and a `fetch` handler, wired by an `[[actors]]` binding. Run `telnyx-edge dev` from the directory that holds the manifest, or point at it with `-f/--from-dir`. Without a `telnyx.toml`, the command errors:

  ```
  ❌ No project manifest found
  💡 Run 'telnyx-edge dev' from a directory containing a telnyx.toml manifest.
  ```

  The [Quick Start](/docs/edge-compute/stateful-actors/quick-start) scaffolds exactly this shape with `telnyx-edge new-func --actor`.

## The Loop

From an umbrella project directory:

```bash theme={null}
telnyx-edge dev
```

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

```bash theme={null}
B=http://localhost:8787

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

Each `env.ACCOUNT.idFromName(...)` call routes to a real actor instance in the local stack — the same code path that runs deployed. Edit your actor class or `fetch` handler and save; `telnyx-edge dev` watches the source and hot-reloads the affected runtime. Actor state lives in the stack's Postgres store, so it **survives a reload** — `alice` is still `70` after you edit and save.

Press **Ctrl-C** to stop watching. The stack keeps running; the command only detaches the file watcher.

## What the Stack Contains

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

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

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

## Flags

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

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

## Notes

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

## Next Steps

* [Quick Start](/docs/edge-compute/stateful-actors/quick-start) — scaffold, write, and deploy an `Account` actor end to end
* [Project structure](/docs/edge-compute/stateful-actors/guides/project-structure) — the two-export shape `telnyx-edge dev` runs
* [Deploy](/docs/edge-compute/deploy) — ship, revisions, and rollback