Skip to main content
Vexa Lite packs every control-plane service into a single image (vexaai/vexa-lite) and runs bots and agent workers as in-container processes (RUNTIME_BACKEND=process) — no Docker socket, no per-bot containers. Two sidecars carry state: Postgres and MinIO. Lite is one of the three supported deploy paths (lite · compose · Kubernetes) and ships from the same images and contracts.

​
Quick start

make lite (= make -C deploy/lite all) writes a minimal .env if you don’t have one, pulls vexaai/vexa-lite:$IMAGE_TAG (default v012; a locally built vexa-lite:dev wins when present), starts the vexa-lite-postgres and vexa-lite-minio sidecars on the vexa-lite-net Docker network, boots the app container, waits on the gateway health endpoint, and probes the three front doors: On first boot Lite mints its own credentials — a [email protected] user and bot,tx-scoped API keys — and hands them to the terminal, so http://localhost:3001 opens signed in. Set VEXA_API_KEY in .env to bring your own key and skip the minting. Don’t have a key yet? Hosted: sign in at vexa.ai/signin with a Google account and copy your key from your account page — free credit, no card required. Self-hosted: make all prints a key when the stack comes up. Transcription needs a backend: point TRANSCRIPTION_SERVICE_URL / TRANSCRIPTION_SERVICE_TOKEN at a transcription unit, or run the bundled CPU sidecar:
Without a transcription backend, bots join and capture but produce no text — a default POST /bots answers 503 unless the spawn opts out (capture-only).

​
What’s in the container

One supervisord tree runs the services a compose deployment spreads across containers: Bots and agent workers are not supervisord programs — the runtime spawns them as child processes, one per meeting and per agent dispatch. Inspect a running deployment with:

​
Configuration

Lite reads the repo-root .env (via docker run --env-file) plus the flags the Makefile sets explicitly. Every key in the configuration reference applies; mind its warning about inline # comments in .env values — it exists because of Lite’s --env-file semantics. If ~/.claude/.credentials.json exists on the host, make lite mounts it read-only into the container so agents run on your Claude subscription without copying credentials into .env.

​
Persistence and upgrade

State lives in the sidecars’ named volumes and survives app-container replacement: Upgrading is re-running with a newer image: set IMAGE_TAG in .env (pin a specific release so deploys are reproducible), then make lite again — it replaces the app container and leaves the sidecars and their volumes untouched. Schema converges in-process on service startup; there is no separate migration step.

​
Is this install actually working? — make probe SURFACE=lite

The probe mints a key and drives the whole journey — spawn → boot → join → transcribe → live-view → stop. Lite runs the real bot in-process, so a dead meeting URL ends in a truthful named failure, never a fake green. The container also carries a Docker HEALTHCHECK on the gateway’s /health (30s interval, 120s start period).

​
Limits vs compose and Kubernetes

  • One shared display. Bots share a single Xvfb — best for one browser session at a time. Compose isolates bots in containers; the Helm chart gives each bot its own Pod.
  • Ephemeral Valkey. In-container with no volume by default.
  • Agent API is not gateway-fronted. Clients reach :8100 directly; gateway-fronting is roadmap.
  • No MCP service. The compose stack’s /mcp surface does not exist in Lite.
  • Sidecar ports are unpublished. Postgres and the MinIO console are reachable only on the Docker network, not from the host.
Outgrown it? Switch to compose — same images, same contracts. Per-feature honest status: Roadmap → Status.