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

# Quickstart

> Run the platform locally, create an agent identity, and test a turn.

This guide gets the current OpenDot platform, database, API, and local voice runtime running.

## 1. Run with Docker Compose

From the repository root:

```bash theme={null}
cp .env.example .env
docker compose up --build
```

Add provider keys to the root `.env` before testing live voice sessions. The
default Sandwich Browser Test path needs both `OPENAI_API_KEY` and
`DEEPGRAM_API_KEY`; Speech-to-speech Browser Test and Speech-to-speech Dot
device sessions use `OPENAI_API_KEY` through the runtime. The rest can stay at
the defaults. Create those keys from the
[Deepgram Console](https://console.deepgram.com/) and the
[OpenAI platform](https://platform.openai.com/).

Open:

```text theme={null}
http://localhost:5173
```

Create a local account on the auth page, then open **Agent Studio**. See
[Login and signup](/login-signup) for how local credentials and Supabase Auth
work.

The Compose stack starts PostgreSQL, applies migrations, serves the web console, and exposes the voice runtime at `http://localhost:8787`. The default local run uses OpenDot email/password auth; Supabase Auth can be enabled later with `SUPABASE_URL`, `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY`, and a Supabase `POSTGRES_URI`.

## 2. Create and test an identity

1. Open **Agent Studio**.
2. Create an agent identity with a name and description.
3. Open **Configuration** and review the default pipeline.
4. Open **Browser Test**.
5. Click **Connect**.
6. Click **Start mic** and speak.
7. Stop speaking and wait for the assistant text and audio chunks.

Agents default to the Sandwich architecture:

```text theme={null}
Deepgram VAD -> Deepgram STT -> OpenAI-compatible LLM -> Deepgram TTS
```

To test the current Speech-to-speech browser path, switch the active agent in
**Configuration** before opening **Browser Test**. That mode asks the platform
API for a realtime browser-session token, has the runtime mint an OpenAI
Realtime client secret, then connects the browser to OpenAI Realtime over native
WebRTC. If you bind the same Speech-to-speech agent to a Dot device, the device
keeps using `/ws` and the runtime opens the OpenAI Realtime WebSocket bridge.

## 3. Optional pnpm workflow

Use this workflow when you want each service in its own terminal.

From the repository root:

```bash theme={null}
corepack enable
corepack prepare pnpm@11.1.3 --activate
pnpm install
pnpm --filter ./platform run db:migrate
```

Start the API, web console, and runtime in separate terminals:

```bash theme={null}
# terminal 1
pnpm run api

# terminal 2
pnpm run dev

# terminal 3
pnpm run runtime
```

Open the Vite URL printed in the terminal. It is usually:

```text theme={null}
http://localhost:5173
```

Add real provider keys to the root `.env` before using the runtime:

```bash theme={null}
DEEPGRAM_API_KEY=...
OPENAI_API_KEY=...
OPENAI_BASE_URL=
OPENAI_MODEL=gpt-5-mini
OPENAI_MAX_OUTPUT_TOKENS=512
OPENAI_REASONING_EFFORT=low
OPENAI_VERBOSITY=low
```

## 4. Optional device check

Open **Dot Device** to claim a spoken device code, refresh runtime availability,
and bind the active identity config to the device.

Bound devices follow the saved architecture. Sandwich agents use the existing
Deepgram plus LLM plus TTS runtime path; Speech-to-speech agents use the runtime
Realtime bridge without changing firmware.

The default runtime endpoints are:

```text theme={null}
WebSocket: ws://localhost:8787/voice
HTTP:      http://localhost:8787
```

## Next steps

* [Platform architecture](/architecture) explains the whole repo and runtime boundary.
* [Configuration](/configuration) explains the Sandwich stage controls and Speech-to-speech browser/device settings.
* [Database inspection](/database-inspection) shows how to inspect PostgreSQL rows with Drizzle Studio.
* [Authentication](/authentication) covers local email/password auth and Supabase Auth.
* [Render deployment](/render-deployment) covers hosted preview deployment.