Skip to main content

​
Prerequisites

ToolVersionPurpose
Python3.12+Backend + agent worker
Node.js18+Dashboard UI + VUI widget
PostgreSQL16Primary database
Redis7+Cache + Celery broker
Docker24+Containerized services
GitLatestSource control

​
Architecture Reminder

​
Step-by-Step Setup

1

Clone the Repository

git clone https://github.com/vaani-ai/voice-agent-platform.git
cd voice-agent-platform
2

Start PostgreSQL & Redis

The easiest way is Docker:
cd agent-studio-backend
docker-compose up db redis -d
This starts PostgreSQL 16 on port 5432 and Redis 7 on port 6379.
3

Set Up Backend

cd agent-studio-backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp app/env/.env.example app/env/.env
# Edit .env with your credentials (see Environment Variables page)

# Run database migrations
alembic upgrade head

# Start the backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
The --reload flag enables hot-reloading. The server restarts automatically when you save code changes.
4

Set Up Agent Worker

cd agent-studio-livekit-agent

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with LiveKit and API keys

# Start in development mode
python agent.py dev
The agent worker requires a running LiveKit server. See the LiveKit docs for self-hosted setup, or use LiveKit Cloud for development.
5

Set Up Dashboard UI

cd agent-studio-ui

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Set NEXT_PUBLIC_ML_BACKEND_URL=http://localhost:8000
# Set JWT_API_SECRET (same as backend)

# Start dev server
npm run dev
Dashboard is now available at http://localhost:3000.
6

Set Up VUI Widget (Optional)

cd agent-studio-vui-widget

# Install dependencies
npm install

# Start dev server
npm run dev
Widget dev server runs at http://localhost:5173.

​
Verify Your Setup

After starting all services, verify everything is working:
CheckHow
Backend APIcurl http://localhost:8000/docs — should show Swagger UI
Databasecurl http://localhost:8000/agents — should return []
DashboardOpen http://localhost:3000 — should show login page
Redisredis-cli ping — should return PONG

​
Running Celery Workers

For batch calling functionality, start the Celery worker and scheduler: 
cd agent-studio-backend
celery -A app.workers.celery_app worker --loglevel=info

​
Common Setup Issues

IssueCauseFix
alembic upgrade failsDatabase doesn’t existCreate DB first: createdb agent_studio_db
Redis connection refusedRedis not runningStart with docker-compose up redis -d
JWT errors on UISecret mismatchEnsure JWT_API_SECRET is identical in backend and UI
Agent worker won’t startMissing LiveKit credentialsVerify LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET
S3 URL errorsStray quotes in env varRemove surrounding quotes from S3_REGION value