Quickstart - LemonSlice

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 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 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 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 project (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET)
A LemonSlice API key
Node.js and uv

1. Clone the repo

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.

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:

.env.local

# --- 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 project settings
`LEMONSLICE_API_KEY`	LemonSlice API keys
`AGENT_NAME`	Any dispatch name — default `lemonslice` works for local dev

3. Install dependencies

npm install
cd agent && uv sync && cd ..

4. Run locally

npm run dev:all

This starts the web app and agent worker together. Open 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.

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 npm package to detect when the avatar’s first video frame has rendered before showing the live avatar — not on ParticipantConnected. See Production checklist 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 and connect via the LiveKit Agents Playground. Come back to 03-livekit-app-python when you’re ready to ship a UI.

​What you’ll run

​Prerequisites

​1. Clone the repo

​2. Set environment variables

​3. Install dependencies

​4. Run locally

​5. Customize your avatar

​What’s already handled for you

​Agent-only prototyping

​Next steps

LiveKit integration

Production checklist

What you’ll run

Prerequisites

1. Clone the repo

2. Set environment variables

3. Install dependencies

4. Run locally

5. Customize your avatar

What’s already handled for you

Agent-only prototyping

Next steps