> ## Documentation Index
> Fetch the complete documentation index at: https://lemonslice.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Run a production-quality LiveKit + LemonSlice avatar app locally in minutes.
The fastest way to a **good** avatar experience is our LiveKit starter project — a Next.js frontend, token server, and Python agent worker wired together with the patterns we recommend for production (ringing UI, secure tokens, avatar readiness handling).
## What you'll run
[`03-livekit-app-python`](https://github.com/lemonsliceai/lemonslice-examples/tree/main/03-livekit-app-python) is a complete app you can clone and run locally:
| Component | What it does |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Next.js app** + `/api/token` | Browser UI and a server-side token endpoint (keeps your LiveKit secret off the client) |
| **`agent/` worker** | LiveKit Agents worker with STT, LLM, TTS via [LiveKit Inference](https://docs.livekit.io/agents/models/) and the LemonSlice avatar plugin |
Avatar video takes a few seconds to initialize. The starter project stays in a **ringing state** and uses the [`@lemonsliceai/avatar`](https://www.npmjs.com/package/@lemonsliceai/avatar) npm package to detect when the avatar's first video frame has rendered — then it transitions to the full in-call layout. This avoids the black-screen flash you get if you show video as soon as the participant joins.
## Prerequisites
* A [LiveKit Cloud](https://cloud.livekit.io/) project (`LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`)
* A [LemonSlice API key](https://lemonslice.com/agents/api)
* [Node.js](https://nodejs.org/) and [uv](https://docs.astral.sh/uv/getting-started/installation/)
## 1. Clone the repo
```bash theme={null}
git clone https://github.com/lemonsliceai/lemonslice-examples.git
cd lemonslice-examples/03-livekit-app-python
```
## 2. Set environment variables
**Required before you run the app.** The starter will not connect without a filled-in `.env.local`. Do not skip this step — copy the example file, then replace every placeholder with your own credentials.
```bash theme={null}
cp .env.example .env.local
```
Edit `.env.local` at the repo root (both Next.js and the agent worker read it). Replace the placeholders with your values:
```bash .env.local theme={null}
# --- Shared (Next.js `/api/token` + LiveKit agent worker) ---
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
AGENT_NAME=lemonslice
# --- Agent only ---
LEMONSLICE_API_KEY=your_lemonslice_api_key
```
| Variable | Where to get it |
| ------------------------------------------------------ | ------------------------------------------------------------ |
| `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | [LiveKit Cloud](https://cloud.livekit.io/) project settings |
| `LEMONSLICE_API_KEY` | [LemonSlice API keys](https://lemonslice.com/agents/api) |
| `AGENT_NAME` | Any dispatch name — default `lemonslice` works for local dev |
## 3. Install dependencies
```bash theme={null}
npm install
cd agent && uv sync && cd ..
```
## 4. Run locally
```bash theme={null}
npm run dev:all
```
This starts the web app and agent worker together. Open [http://localhost:3000](http://localhost:3000), join a room, and talk to your avatar.
If the app fails to connect, confirm `.env.local` is filled in (step 2) and restart both processes.
Prefer two terminals? Run `npm run dev` in one and `npm run dev:agent` in the other. Same result.
## 5. Customize your avatar
Open `agent/src/agent.py` and change `AGENT_IMAGE_URL` to any publicly accessible face image. You can also swap STT, LLM, and TTS models in that file.
For every `AvatarSession` option (agent ID, idle timeout, events, shutdown), see [LiveKit integration](/docs/livekit).
## What's already handled for you
These are the production patterns baked into the starter project — you get them for free by starting here:
**Secure token server.** Browsers never see `LIVEKIT_API_SECRET`. Your Next.js route signs a short-lived JWT; the client connects with `{ token, serverUrl, room }`. See the repo README for the `/api/token` contract.
**Ringing → active UI.** The frontend uses the [`@lemonsliceai/avatar`](https://www.npmjs.com/package/@lemonsliceai/avatar) npm package to detect when the avatar's first video frame has rendered before showing the live avatar — not on `ParticipantConnected`. See [Production checklist](/docs/reference/production-checklist#handle-avatar-connect-disconnect-events) for the full pattern and disconnect handling.
**Agent dispatch.** The worker registers under `AGENT_NAME` so LiveKit routes room jobs to your agent automatically.
## Agent-only prototyping
If you just want to iterate on the agent without a frontend, use [`02-livekit-playground-demo`](https://github.com/lemonsliceai/lemonslice-examples/tree/main/02-livekit-playground-demo) and connect via the [LiveKit Agents Playground](https://docs.livekit.io/agents/start/playground). Come back to `03-livekit-app-python` when you're ready to ship a UI.
## Next steps
Full configuration, RPC events, and graceful shutdown.
Agent stack, latency, call lifecycle, and production hardening.