Skip to main content
Use this quickstart to run the LiveKit Agent + SpatialReal Avatar demo quickly. This page focuses on clone-and-run. The frontend is built with AvatarKit UI, and code-level explanation is in a separate Guide page.

GitHub Repository

Source code for this quickstart.

Code Walkthrough

Backend and frontend architecture walkthrough.

​
How LiveKit + SpatialReal Work Together

In this architecture, each system has a clear responsibility:
  • LiveKit handles room lifecycle, client/worker connectivity, microphone transport, and agent dispatch.
  • SpatialReal takes agent response audio, generates lip-sync + avatar animation, and publishes avatar output back into the room.
  • Frontend only needs to join LiveKit and render with AvatarKit UI

​
Prerequisites

  • Node.js 18+
  • Python 3.10+
  • pnpm
  • uv
  • SpatialReal credentials (SPATIALREAL_API_KEY, SPATIALREAL_APP_ID, SPATIALREAL_AVATAR_ID)
  • LiveKit credentials (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET)
  • Gemini key (GOOGLE_API_KEY)
1

Clone the repo and enter the quickstart folder

git clone https://github.com/spatialwalk/avatarkit-voice-agent-demo.git
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart
2

Create env files

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
Fill backend/.env:
backend/.env
LIVEKIT_URL=wss://your-project.livekit.cloud # https://cloud.livekit.io
LIVEKIT_API_KEY=your_api_key # https://cloud.livekit.io
LIVEKIT_API_SECRET=your_api_secret # https://cloud.livekit.io

GOOGLE_API_KEY=your_google_api_key # https://aistudio.google.com/api-keys
E2E_GOOGLE_MODEL=gemini-2.5-flash-native-audio-preview-12-2025
E2E_GOOGLE_VOICE=Puck

SPATIALREAL_API_KEY=your_api_key # https://app.spatialreal.ai/apps
SPATIALREAL_APP_ID=your_app_id # https://app.spatialreal.ai/apps
SPATIALREAL_AVATAR_ID=6aed28f9-674c-4ffb-89ee-b447b28aa3ed # https://app.spatialreal.ai/avatars/library
Fill frontend/.env:
frontend/.env
VITE_SPATIALREAL_APP_ID=your_app_id # https://app.spatialreal.ai/apps
VITE_SPATIALREAL_AVATAR_ID=6aed28f9-674c-4ffb-89ee-b447b28aa3ed # https://app.spatialreal.ai/avatars/library
VITE_TOKEN_ENDPOINT=http://localhost:8080/token
VITE_ROOM_NAME=voice-agent-room
3

Install dependencies

# backend
cd backend
uv sync

# frontend
cd ../frontend
pnpm install
4

Run the stack (3 terminals)

# Terminal 1: token server
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/backend
uv run token_server.py

# Terminal 2: LiveKit agent worker
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/backend
uv run agent.py dev

# Terminal 3: frontend
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/frontend
pnpm dev
Open http://localhost:3000, click Connect, then Enable Mic to start speaking.

​
Next