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

# Run it locally

> Run the Playground on your own machine, point it at hosted or local speech, and understand its transport. The playground ships inside supervoice; one command builds the UI and serves the agent.

## What you are running

The Playground is a Vite + React SPA (`playground/web/`) served by a small Python
**harness** that runs the agent in-process. It ships inside the **supervoice**
repo, which pins `unpod` and `superdialog` as editable sibling deps, plus bundled
example flows and playbooks - so it runs self-contained.

> [!NOTE]
>
> Agent flows are authored with **superdialog**; the call runtime is the **unpod**
> SDK `AgentRunner`. The harness re-implements the WS audio protocol from scratch -
> there is no `pipecat` / `rtvi` client dependency.

## Prerequisites

> [card] An LLM key
>
> `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Copy `playground/.env.example` to
> `.env` at the repo root and set it.

> [card] A speech backend
>
> Something the harness can reach for audio. Resolved in the order below - a
> fresh clone needs no local supervoice if you use a hosted URL.

### How the speech backend is resolved

The harness (`harness/api.py`) picks a backend in this order:

1. **`UNPOD_BASE_URL`** → the hosted `wss://<host>` speech service. For hosted
   voice with zero local backend: `UNPOD_BASE_URL=api.unpod.ai` plus
   `UNPOD_API_KEY=<key>`.
2. Otherwise **`ws://127.0.0.1:9000`** → a local `supervoice-dev`.

> [!NOTE]
>
> Legacy `SUPERVOICE_URL` still overrides both if set (with a deprecation warning) -
> prefer `UNPOD_BASE_URL`. The harness boots and serves the UI even with no speech
> backend reachable; only clicking **Connect** (which opens an audio call) needs one.

## Run it

From the `supervoice/` repo root (`cp playground/.env.example .env`, set an LLM key):

```bash theme={null}
task pg        # builds web/dist, then serves UI + in-process agent on :9100
```

Or manually:

```bash theme={null}
cd playground/web && npm install && npm run build && cd ../..
uv run --extra playground python -m playground.run
```

Open [http://localhost:9100](http://localhost:9100), click **Connect**, allow the mic, and talk.

> [card] One-click Docker
>
> `task pg-docker` - playground on `:9100` + local dev-speech on `:9000`, in
> containers. Set `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` in `supervoice/.env` first.

> [card] Local speech
>
> `task pg-stack` - boots a local dev-speech on `:9000` unless a hosted speech
> URL is set.

### Frontend hot-reload loop

Run the harness on `:9100` and Vite separately on `:5173` (it proxies
`/playground/*` to the harness):

```bash theme={null}
uv run python -m playground.run          # terminal 1 - harness :9100
cd playground/web && npm run dev          # terminal 2 - Vite :5173
```

## Architecture (M1)

Two planes, deliberately separate:

Playground architecture (M1)

Browser

Playground webweb/ · mic 16 kHz up, playback 24 kHz down

audioevents

Servers

Remote supervoiceWS /ws/audio, protobuf frames · UNPOD\_BASE\_URLHarness · api.pyPOST /playground/sessions · WS /playground/events

The harness's AgentRunner registers with supervoice. Session hooks feed the events plane, not the audio bridge.Unpod runs itYou run it

* **Audio** rides the supervoice WS bridge directly (16 kHz mic up, 24 kHz
  playback down). The wire codec is a small proto3 `Frame` encoder/decoder in
  `web/src/transport/protobuf.ts`; capture/playback in `web/src/transport/audio.ts`.
* **Transcript / current checkpoint** ride the harness's **own** side channel
  (`/playground/events`), fed by SDK `Session` hooks - *not* the audio bridge.
  This keeps the transcript accurate even when audio is under load.

## Configuration

One host + one credential drive every unpod plane. The harness derives the auth,
platform, playbook-API, and hosted-speech bases from `UNPOD_BASE_URL` via the
unpod SDK resolver.

| Setting | Purpose |
| - | - |
| `UNPOD_BASE_URL` | The one host every plane is derived from (e.g. `api.unpod.ai`). |
| `UNPOD_API_KEY` | Credential for hosted speech + platform APIs. |
| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | The LLM the agent and builder run on. |
| `FLOWS_DIR` / `PLAYBOOKS_DIR` | Point at `../superdialog/examples/*` to drive live superdialog copies instead of the bundled ones. |

> [!NOTE]
>
> Default builds bake no client-side auth base - the SPA reaches auth through the
> harness's same-origin proxy at `/playground/auth`. The deprecated `VITE_API_URL`
> still overrides this (pointing the SPA straight at a hosted backend) if set
> explicitly mid-migration.

## Related

> [card] [SuperDialog engine](https://docs.unpod.ai/superdialog/introduction.md)
>
> The brain behind every playbook - engines, the Agent protocol, and embedding.

> [card] [Embedding guides](https://docs.unpod.ai/superdialog/embedding-guides/overview.md)
>
> Drop SuperDialog into LiveKit, PipeCat, FastAPI, or the CLI directly.

> [card] [Speech Stack](https://docs.unpod.ai/agent-sdk/overview.md)
>
> The voice infrastructure that serves live calls in production.

> [card] [Build an agent playbook](https://docs.unpod.ai/agent-studio/build-an-agent.md)
>
> The builder-facing walkthrough of the same Playground.


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