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 the recordings storage (versitygw, an S3 server that keeps each recording as a plain file in a volume). 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-storage sidecars on the vexa-lite-net Docker network, boots the app container, waits on the gateway health endpoint, and probes the three front doors, giving each up to two minutes to answer (on first boot the terminal restarts once the self-host key is minted): 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: The storage sidecar runs versity/versitygw (Apache-2.0), pinned by tag and digest in deploy/lite/Makefile. meeting-api reaches it over S3 at vexa-lite-storage:9000 with the MINIO_* settings the Makefile passes (the names are unchanged; the credentials default to vexa-access-key / vexa-secret-key and can be overridden on the make command line). Its port is not published. Back the volume up with a copy that keeps extended attributes (rsync -aX, cp -a); see Recordings → Backups. 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. Coming from a Lite that ran MinIO: old recordings stay in vexa-lite-miniodata and do not play back until copied. make lite starts on the new storage without inspecting the old volume. Run make -C deploy/lite migrate-storage to copy and verify objects by SHA-256; it never deletes the old volume. Where your recordings live now covers the copy and rollback.

​
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 storage sidecar’s S3 port are reachable only on the Docker network, not from the host.
  • No authenticated bots. Lite does not package the provisioning flow or a userdata store (Authenticated bots).
Outgrown it? Switch to compose — same images, same contracts. Per-feature honest status: Roadmap → Status.