Vexa Lite Deployment

Deploy Vexa as a single Docker container with no GPU requirements. Vexa Lite bundles all services into one image, managed by supervisord.

One-click platform deployments: For platform-specific guides (Fly.io, Railway, Render, etc.), see the vexa-lite-deploy repository.

Overview

Why Vexa Lite?

Single container — All services bundled, no multi-service orchestration
Stateless — All data stored in your database; easy to redeploy
No GPU required — Uses the Vexa remote transcription service
Built-in Redis — No external Redis needed (optional external Redis supported)
Interactive bots — TTS (text-to-speech) and virtual camera included

Included Services

Vexa Lite runs the following services internally via supervisord:

Service	Internal Port	Description
API Gateway	8056	Main entry point (the only exposed port)
Admin API	8057	User and API token management
Meeting API	8080	Bot orchestration + transcription pipeline
Runtime API	8090	Container lifecycle — process backend
Agent API	8100	AI agent chat runtime
Dashboard	3000	Next.js web UI
MCP Service	18888	Model Context Protocol for Claude/Cursor
TTS Service	8059	Text-to-speech
Redis	6379	Built-in message broker
Xvfb	—	Virtual display for headless browsers
PulseAudio	—	Audio server for TTS playback

All internal services communicate over localhost. Only port 8056 is exposed externally.

Quick Start

Production: Remote Database

docker run -d \
  --name vexa \
  -p 8056:8056 \
  -e DATABASE_URL="postgresql://user:password@your-db-host:5432/vexa" \
  -e DB_SSL_MODE="require" \
  -e ADMIN_API_TOKEN="your-secret-admin-token" \
  -e TRANSCRIPTION_SERVICE_URL="https://transcription.vexa.ai/v1/audio/transcriptions" \
  -e TRANSCRIPTION_SERVICE_TOKEN="your-transcription-api-key" \
  -e OPENAI_API_KEY="sk-your-openai-key" \
  vexaai/vexa-lite:latest

Production: Use immutable tags (e.g., 0.10.0-260405-0108) instead of :latest for reproducible deployments.

Development: Local Database

# Create network
docker network create vexa-network

# Start PostgreSQL
docker run -d \
  --name vexa-postgres \
  --network vexa-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=vexa \
  -p 5432:5432 \
  postgres:latest

# Start Vexa Lite
docker run -d \
  --name vexa \
  --network vexa-network \
  -p 8056:8056 \
  -e DATABASE_URL="postgresql://postgres:your_password@vexa-postgres:5432/vexa" \
  -e ADMIN_API_TOKEN="your-secret-admin-token" \
  -e TRANSCRIPTION_SERVICE_URL="https://transcription.vexa.ai/v1/audio/transcriptions" \
  -e TRANSCRIPTION_SERVICE_TOKEN="your-transcription-api-key" \
  -e OPENAI_API_KEY="sk-your-openai-key" \
  vexaai/vexa-lite:latest

The container automatically runs database migrations on startup. Fresh databases are initialized with the full schema.

Environment Variables

Required

DATABASE_URL

string

required

PostgreSQL connection string. Supports both postgresql:// and postgres:// schemes.Example: postgresql://user:pass@host:5432/vexaAlternatively, set individual variables: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD.

ADMIN_API_TOKEN

string

required

Secret token for admin operations (creating users, minting API tokens).

TRANSCRIPTION_SERVICE_URL

string

required

Transcription service endpoint.Default: https://transcription.vexa.ai/v1/audio/transcriptions

TRANSCRIPTION_SERVICE_TOKEN

string

required

API key for the transcription service. Get yours from vexa.ai/account.

Database

You can use DATABASE_URL or individual variables. If both are provided, DATABASE_URL takes precedence.

DB_HOST

string

default:"localhost"

PostgreSQL hostname.

DB_PORT

string

default:"5432"

PostgreSQL port.

DB_NAME

string

default:"vexa"

Database name.

DB_USER

string

default:"postgres"

Database user.

DB_PASSWORD

string

Database password.

DB_SSL_MODE

string

default:"disable"

SSL mode for database connections. Set to require for cloud-hosted databases (Supabase, Neon, AWS RDS, etc.).

Redis

Vexa Lite includes a built-in Redis server. If REDIS_HOST is localhost or unset, the internal Redis is used automatically. To use an external Redis, set REDIS_HOST to your Redis server address.

REDIS_HOST

string

default:"localhost"

Redis hostname. Set to an external address to use external Redis instead of the built-in server.

REDIS_PORT

string

default:"6379"

Redis port.

REDIS_URL

string

Full Redis URL. If provided, individual Redis vars are parsed from it.Example: redis://user:password@redis-host:6379/0

Interactive Bots (TTS & Virtual Camera)

The OpenAI TTS dependency is temporary. A fully local TTS engine (no external API keys required) is planned — see issue #130.

OPENAI_API_KEY

string

OpenAI API key for text-to-speech (temporary — will be replaced by local TTS, see #130). Required for the /speak command to work. Without this, bots can still join meetings and transcribe, but TTS will be unavailable.

Recording Storage

STORAGE_BACKEND

string

default:"local"

Recording storage backend: local, minio, or s3.

LOCAL_STORAGE_DIR

string

default:"/var/lib/vexa/recordings"

Directory for local recording storage. Mount a volume here for persistence.

S3 / MinIO storage variables

For STORAGE_BACKEND=s3:

Variable	Default	Description
`AWS_REGION`	`us-east-1`	AWS region
`AWS_ACCESS_KEY_ID`	—	AWS access key
`AWS_SECRET_ACCESS_KEY`	—	AWS secret key
`S3_BUCKET`	—	S3 bucket name
`S3_ENDPOINT`	—	Custom S3 endpoint (for non-AWS providers)
`S3_SECURE`	`true`	Use HTTPS for S3 connections

For STORAGE_BACKEND=minio:

Variable	Default	Description
`MINIO_ENDPOINT`	—	MinIO server endpoint (e.g., `minio:9000`)
`MINIO_ACCESS_KEY`	—	MinIO access key
`MINIO_SECRET_KEY`	—	MinIO secret key
`MINIO_BUCKET`	`vexa-recordings`	MinIO bucket name
`MINIO_SECURE`	`false`	Use HTTPS for MinIO connections

Transcription

WHISPER_BACKEND

string

default:"remote"

Transcription backend. Use remote to route audio to the Vexa transcription service (recommended). Use faster_whisper for local CPU-based transcription (slow, development only).

WHISPER_MODEL_SIZE

string

default:"tiny"

Whisper model size when using local transcription (WHISPER_BACKEND=faster_whisper). Options: tiny, base, small, medium.

SKIP_TRANSCRIPTION_CHECK

string

default:"false"

Set to true to skip the startup connectivity check to the transcription service. The URL and API key are still required but won’t be validated at startup.

Logging

LOG_LEVEL

string

default:"info"

Log level for all services. Options: debug, info, warning, error.

Health Check

The container includes a built-in health check that polls the API Gateway:

GET http://localhost:8056/docs

Interval: 30s
Timeout: 10s
Start period: 90s (allows services to initialize)
Retries: 3

Use this with your orchestrator’s health check mechanism:

# Check container health
docker inspect --format='{{.State.Health.Status}}' vexa

Recording Storage

For production, use object storage so recordings persist across container restarts:

docker run -d \
  --name vexa \
  -p 8056:8056 \
  -e STORAGE_BACKEND=s3 \
  -e AWS_ACCESS_KEY_ID="your-key" \
  -e AWS_SECRET_ACCESS_KEY="your-secret" \
  -e S3_BUCKET="vexa-recordings" \
  -e AWS_REGION="us-east-1" \
  -e DATABASE_URL="postgresql://user:pass@host/vexa" \
  -e ADMIN_API_TOKEN="your-admin-token" \
  -e TRANSCRIPTION_SERVICE_URL="https://transcription.vexa.ai/v1/audio/transcriptions" \
  -e TRANSCRIPTION_SERVICE_TOKEN="your-api-key" \
  vexaai/vexa-lite:latest

Production: Use immutable tags (e.g., 0.10.0-260405-0108) instead of :latest.

For local development, mount a volume:

docker run -d \
  -v vexa-recordings:/var/lib/vexa/recordings \
  ...

For the full storage matrix, see Recording storage.

Build from Source

To build the image locally from the Vexa repository:

git clone https://github.com/Vexa-ai/vexa.git
cd vexa/deploy/lite
make build

This produces a vexa-lite:dev image. See make help for additional commands (push, set-latest, etc.).

Database Setup

Supabase

Create a project at supabase.com
Click Connect on the project page
Select method: Session pooler
Copy the connection string
Set DB_SSL_MODE=require

Neon

Create a project at neon.tech
Copy the connection string from the dashboard
Set DB_SSL_MODE=require

Local PostgreSQL

docker network create vexa-network

docker run -d \
  --name vexa-postgres \
  --network vexa-network \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_password \
  -e POSTGRES_DB=vexa \
  -p 5432:5432 \
  postgres:latest

Then run Vexa Lite with --network vexa-network and DB_HOST=vexa-postgres.

Source Code

api-gateway — REST/WebSocket API
meeting-api — bot lifecycle orchestration
dashboard — web UI
admin-api — user and token management

Next Steps

Create users and API tokens: Admin API
Set up a dashboard UI: Vexa Dashboard
Configure interactive bots: Interactive Bots
Platform-specific guides: vexa-lite-deploy repository

Documentation Index

​Overview

​Included Services

​Quick Start

​Production: Remote Database

​Development: Local Database

​Environment Variables

​Required

​Database

​Redis

​Interactive Bots (TTS & Virtual Camera)

​Recording Storage

​Transcription

​Logging

​Health Check

​Recording Storage

​Build from Source

​Database Setup

​Source Code

​Next Steps

Overview

Included Services

Quick Start

Production: Remote Database

Development: Local Database

Environment Variables

Required

Database

Redis

Interactive Bots (TTS & Virtual Camera)

Recording Storage

Transcription

Logging

Health Check

Recording Storage

Build from Source

Database Setup

Source Code

Next Steps