Deployment

Prerequisites

• Python 3.11+
• PostgreSQL 14+ with pgvector extension
• LiveKit server (cloud or self-hosted)
• LLM, STT, TTS providers – self-hosted services with OpenAI-compatible API, or cloud provider API keys

Quick Start

1. Clone the repository

git clone https://github.com/ai-chans/core.git
cd core

2. Install dependencies

pip install -e ".[dev]"

3. Configure environment

cp .env.example .env

Edit .env with your settings:

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/chans

# LiveKit
LIVEKIT_URL=wss://your-livekit.example.com
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

# Admin API
CHANS_ADMIN_API_KEY=your-admin-key

4. Run database migrations

make db-apply

5. Start the services

Start the API server. This is required for the SDK to connect and for the Admin API/Panel to function:

uvicorn chans.server:app --port 8080

Once running, access the Admin Panel at http://localhost:8080/home.

Start the voice agent (in a separate terminal):

python agent.py dev    # Development mode with hot reload
python agent.py start  # Production mode

6. Verify deployment

curl http://localhost:8080/health
# {"status": "ok"}

Configure Provider Presets

Before creating agents, configure provider presets for LLM, STT, and TTS via the Admin Panel:

Admin Panel: http://localhost:8080/home

Navigate to Provider Presets and create presets for each type:

For self-hosted providers, set provider to self-hosted and configure base_url and model in the config.

Create an Agent

In the Admin Panel, navigate to Agents and create a new agent:

1. Set a name and system prompt
2. Select mode: enhanced (built-in AI) or passthrough (webhook to your LLM)
3. Assign your default presets for LLM, STT, and TTS

The agent's token (e.g., agt_xxx) is used with the SDK to connect

Connecting the SDK

Point the SDK to your self-hosted endpoint:

const { connect } = useVoiceAgent({
  agentToken: "agt_xxx",
  apiUrl: "http://localhost:8080",  // Your self-hosted URL
})

Environment Variables

Required

Optional

Database Setup

chans requires PostgreSQL with the pgvector extension:

CREATE EXTENSION IF NOT EXISTS vector;

LiveKit Options

Managed (Recommended)

Use LiveKit Cloud for production:

1. Create a project
2. Copy the URL, API key, and secret
3. Set in your .env

Self-hosted

Deploy your own LiveKit server. See LiveKit docs.

Coming Soon

Docker Deployment – Pre-built Docker images for containerized deployment.

Next Steps

• Admin API Reference – Full endpoint documentation
• SDK Quick Start – Connect your app