> ## 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

`telnyx-acp dev` runs the agent on localhost: the managed loop in the CLI's own process, listening on loopback, reloading `instructions.md` and `agent.json` on save. Nothing is deployed, and the outbound calls are the model's, those of the tools in `agent.json`, and Telnyx recognition and synthesis when the page's voice button is used.

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

```text theme={null}
✓ support-agent (configuration kind) running on this machine
  http://127.0.0.1:8787/agents/support-agent/<conversation>
  telnyx-acp invoke support-agent --conversation alice --local "hi"
  watching instructions.md and agent.json; Ctrl-C to stop
↻ instructions.md changed; the next reply uses it
```

## What Runs Where

| | Under `dev` |
| - | - |
| The loop: turns, message log, state | Local, in the CLI's process. State lives in a temporary directory, removed on stop. |
| The model | An API call to Telnyx inference, with the user's own key. |
| `instructions.md`, `agent.json`, the tools file | Local files, reloaded on save, including a `set` from another terminal. `web`, `phone` and `.env` are read as `dev` starts. |
| Conversations | Local, over loopback: `chat --local`, `invoke --local`, `rpc --local`. |
| The browser page | Served at `http://127.0.0.1:8787/web` when `web` is set as `dev` starts. A `web` added later needs a restart of `dev`. With a number or a `voice` block the page has a mic button, which the deployed page does not offer yet, and shows the agent's number. |
| Scheduled tasks | Local, in process, the moment they are due. |
| Memory | Not called. |
| Calls and texts | Not reachable. No webhook can reach localhost. |
| Secrets | `.env`, read by `dev`. `add secret` is the platform's. |
| Logs | The `dev` terminal. `telnyx-acp logs` is the platform's. |

## What Works Locally

| Feature | Locally | Deployed |
| - | - | - |
| Turns with `chat`, `invoke`, `rpc`, with `--stream` | Yes | Yes |
| The browser page at `/web` | Yes | Yes |
| Editing the instructions or the model, applied on save | Yes | Edit and `deploy` |
| Memory | No | Yes |
| Calls and texts | No | Yes |
| STT, TTS and the `voice` block, through the page's mic button | Yes, with `web` and a number or a `voice` block; `eager`, `filler` and `harness` apply on calls only | Yes, on calls |
| Tools (Web Search and MCP servers), on text turns | Yes | Yes |
| Approvals (`ask`) | Yes | Not yet: a deployed run with an `ask` tool pauses and cannot be decided |

So a local pass is for the instructions, the model and the shape of a conversation. Anything that needs a number or a profile needs a `deploy`.

## Talking to It

There are two ways to put a turn into the running agent from a second terminal, both with `--local` so that the turn goes to `dev` instead of the deployed agent.

`chat` is interactive: it opens one conversation and keeps it open, and each line typed is a turn on it.

```bash theme={null}
telnyx-acp chat --local
```

```text theme={null}
✔ chatting with support-agent (conversation session-b969, on this machine)
   /exit or Ctrl-C leaves, /new starts a fresh conversation
› my name is Alex
✔ support-agent is answering 2.0s
support-agent › Hi Alex! How can I help you today?
› what's my name?
✔ support-agent is answering 1.0s
support-agent › Your name is Alex.
› /exit
to continue this conversation:
$ telnyx-acp chat support-agent --conversation session-b969 --local
```

`invoke` is one turn per command, on the conversation it names, so turns across conversations can interleave:

```bash theme={null}
telnyx-acp invoke support-agent --conversation alice --local "hi"
telnyx-acp invoke support-agent --conversation bob --local --stream "hi"
```

## Secrets

`dev` never reads the platform's secrets. It reads the project's `.env`, merged with the shell environment, and reads three kinds of value from it: `TELNYX_API_KEY` for the model, or the session `telnyx-acp login` keeps, read before every call; a third-party provider's key under the same name `deploy` reads it from as a secret, `OPENAI_API_KEY` for an `openai/*` model and likewise `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY` and `GROQ_API_KEY`; and the secret an `mcp` tool entry names, under that name. `.env` is read once, as `dev` starts, so an edit needs a restart. `TELNYX_PUBLIC_KEY` does not apply locally: it verifies webhooks, and none arrive.

The login session renews itself: when the access token is expired or about to be, the next turn renews it from the refresh token, and nothing is asked of you. A renewal the platform refuses fails that turn with `Your session has expired; dev needs a key to reach the model`; a `login` in another terminal is picked up by the next turn.