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

# Deploy

> Run AgentRunner in production: reachability, authentication, scaling, and shutdown.

An `AgentRunner` is a long-lived process: it registers with the Unpod
orchestrator over WSS and heartbeats (at an interval the orchestrator assigns on
registration). Under the default `dial_out` transport it then **dials out** to a
per-call bridge each time a call is assigned; under the legacy `serve` transport
it instead hosts a bridge connection per call. Provisioning is covered
by the [Provisioning checklist](https://docs.unpod.ai/agent-sdk/setup-checklist.md); this page is what
changes when you leave your laptop.

> [!NOTE]
>
> Since v2 the runner defaults to the `dial_out` transport: both the control
> connection and the per-call bridge are **outbound** from the runner, so a runner
> behind NAT needs no public reachability, `serving_url`, or `agent_secret`. The
> reachability and authentication steps below apply only when you opt into the
> legacy `transport="serve"` model. See
> [AgentRunner constructor](https://docs.unpod.ai/agent-sdk/agent-runner.md#constructor).

## What production needs

A production deployment should have:

* A stable `UNPOD_PLATFORM_TOKEN` + `UNPOD_ORG_HANDLE` - **required by the `AgentRunner`** for the orchestrator connection ([full variable table](https://docs.unpod.ai/agent-sdk/setup-checklist.md#environment-variables))
* A clear `agent_id` shared by every replica of the same agent
* Capacity limits (`max_sessions`, `permits_per_minute`) that match your traffic
* Shutdown handling so active calls can drain before the process exits
* Observability for active calls, failures, and latency
* **(legacy `serve` transport only)** a public `serving_url` so Unpod can reach the runner bridge, and an `agent_secret` so inbound bridge connections are signed and verified

If you are writing docs for app developers, this is the minimum contract:

1. Set the environment variables.
2. Run multiple replicas with the same `agent_id` when you need scale.
3. Restart the process under a supervisor.
4. **(legacy `serve` transport only)** expose the runner publicly and lock down the bridge with `UNPOD_AGENT_SECRET`.

## Production checklist

### 1. Reachability - `serving_url` (legacy `serve` transport only)

> [!NOTE]
>
> This step applies only to `transport="serve"`. Under the default `dial_out`
> transport the runner never listens - it dials out to the bridge URL delivered in
> each `job.assign` frame - so no public reachability is needed.

In `serve` mode the runner hosts a per-call bridge that Unpod dials into. It
binds to `0.0.0.0:8765` by default; in production, tell the orchestrator where
that bridge is publicly reachable:

```bash theme={null}
export UNPOD_RUNNER_URL="wss://agents.example.com:8765"
```

(or pass `serving_url=...` to `AgentRunner`). The host/port must be reachable
from Unpod.

### 2. Authentication - `agent_secret` (legacy `serve` transport only)

> [!NOTE]
>
> Also `serve`-only. Under the default `dial_out` transport the per-call bridge is
> authenticated by the per-call token embedded in the `job.assign` `bridge_url`, so
> `agent_secret` is ignored (the constructor warns if you pass it).

In `serve` mode, with an agent secret set, every inbound bridge connection is
HMAC-verified (signed URLs, replay-protected). Without one, the runner accepts
unsigned connections - acceptable only for local dev.

```bash theme={null}
export UNPOD_AGENT_SECRET="a-long-random-secret"
```

### 3. Capacity

```python theme={null}
AgentRunner(
    entrypoint=handle_call,
    agent_id="my-agent",
    max_sessions=50,          # orchestrator never dispatches beyond this
    permits_per_minute=120,   # rate of new call acceptance
    drain_timeout_s=60,
)
```

### 4. Scaling - add replicas

Run more processes with the **same `agent_id`** - on one machine or many. They
form a pool; the orchestrator load-balances dispatches across replicas by
reported capacity. No shared state, no coordination needed.

```bash theme={null}
# replica 1, replica 2, ... identical:
UNPOD_PLATFORM_TOKEN=... UNPOD_ORG_HANDLE=your-org python agent.py
```

### 5. Shutdown and supervision

On `SIGTERM` the runner stops accepting dispatches and drains active calls for
up to `drain_timeout_s` before exiting - container- and systemd-friendly.

> [!NOTE]
>
> Under the default `dial_out` transport the runner **auto-reconnects** its
> orchestrator control socket with jittered exponential backoff (1s → 30s cap) and
> re-registers under the same `worker_id`; in-flight calls ride their own bridge
> sockets and survive a control-socket drop. Still run it under a supervisor with
> restart-on-exit (systemd `Restart=always`, Kubernetes restart policy, Docker
> `--restart`) to recover from process crashes and from a non-retriable transport
> rejection (an orchestrator too old to acknowledge `dial_out`). The legacy
> `transport="serve"` model does **not** auto-reconnect.

## Environment summary

The minimum production `.env` - every variable defined in the
[Provisioning checklist](https://docs.unpod.ai/agent-sdk/setup-checklist.md#environment-variables):

```bash theme={null}
UNPOD_PLATFORM_TOKEN="..."                  # AgentRunner + management client
UNPOD_ORG_HANDLE="acme"                     # required with the token
UNPOD_BASE_URL="https://unpod.ai"           # runner derives wss://<host>
UNPOD_SERVICE_BASE_URL="https://unpod.ai"   # management REST, bare host

# Legacy transport="serve" only (ignored under the default dial_out transport):
UNPOD_AGENT_SECRET="long-random-secret"
UNPOD_RUNNER_URL="wss://agents.example.com:8765"
```

Constructor arguments beat the environment:

* `AgentRunner(base_url=...)` overrides `UNPOD_ORCHESTRATOR_URL`
* `AgentRunner(serving_url=...)` overrides `UNPOD_RUNNER_URL`
* `AsyncClient(base_url=...)` overrides `UNPOD_SERVICE_BASE_URL`

## Watch it run

Wire up [metrics and runner stats](https://docs.unpod.ai/speech-stack/observability.md) before you
need them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.