Local Development

Run each service individually for development with hot-reload. No .env files needed — all defaults are hardcoded for local dev.

Prerequisites

Python 3.10+
Node.js 20+
Docker Desktop (for PostgreSQL and MinIO)

1. Start infrastructure

docker compose up -d postgres minio

This starts PostgreSQL (port 5434) and MinIO (port 9002) in Docker. The database nenyax is created automatically.

2. Backend

cd backend

# Create virtual environment
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -e .

# Start the server (runs migrations automatically)
uvicorn app.main:app --reload

Backend runs at http://localhost:8000.

3. Frontend

cd frontend

# Install dependencies
npm install

# Start dev server
npm run dev

Frontend runs at http://localhost:3000.

4. Agent

cd agent

# Create virtual environment
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -e .

# Start the agent
python agent.py dev

The agent requires no .env file. On startup it fetches all API keys (LiveKit, Google, Resemble, STT providers) from the backend dashboard. Make sure the backend is running first and provider keys are configured at API Keys.

Environment

No .env files are needed for local dev. All defaults are hardcoded in the code:

Setting	Default	Source
Database	`postgresql://postgres:nenyax@localhost:5434/nenyax`	`config.py`, `auth.ts`
MinIO	`localhost:9002`, credentials `minioadmin/minioadmin`	`config.py`
Backend URL	`http://localhost:8000/api`	`api.ts`
Auth secret	`authsecret123`	`auth.ts`

.env files are only needed to override a default (e.g., pointing to a different DB host). See Environment Variables for the full reference.

Troubleshooting

Backend can't connect to database

Ensure Docker containers are running: docker compose up -d postgres minio
If you have a backend/.env file, make sure it doesn’t override DATABASE_URL or POSTGRES_PASSWORD with stale values
For a fresh start: docker compose down -v && docker compose up -d postgres minio

Frontend shows 'Failed to fetch' errors

Ensure the backend is running at http://localhost:8000
If you have a frontend/.env file, make sure NEXT_PUBLIC_API_URL isn’t pointing elsewhere

Agent doesn't connect to calls

Ensure the backend is running and all provider keys are configured at API Keys
Verify LiveKit credentials are set and the URL uses wss:// protocol
Check that at least one STT provider key is configured in the dashboard
Check the agent terminal for “Injected N keys from backend dashboard” on startup

Custom agent files not loading

Ensure MinIO is running: docker ps | grep minio
If MinIO was down when an agent was created, the file scaffold may have failed silently — reload the agent editor page to auto-scaffold

Getting Started

Architecture

Configuration

Features

Local Development

Local Development

Prerequisites

1. Start infrastructure

2. Backend

3. Frontend

4. Agent

Environment

Troubleshooting

​Local Development

​Prerequisites

​1. Start infrastructure

​2. Backend

​3. Frontend

​4. Agent

​Environment

​Troubleshooting

Local Development

Prerequisites

1. Start infrastructure

2. Backend

3. Frontend

4. Agent

Environment

Troubleshooting