vexa

Abstract

Open-source meeting transcription API for Google Meet, Microsoft Teams & Zoom. Auto-join bots, real-time WebSocket transcripts, MCP server for AI agents. Self-host or use hosted SaaS.

The Problem

Vexa addresses the pain of meeting data sovereignty—teams needing real-time transcription and bot control for Google Meet, Microsoft Teams, and Zoom without sending meeting data to third-party SaaS platforms. It positions itself as a self-hosted alternative to Recall.ai, Otter.ai, and Fireflies.ai, targeting organizations that must keep meeting data within their own infrastructure. The repository functions as a portfolio of 5 semi-independent projects rather than a single unified codebase.

What This Does

Vexa comprises five project groups totaling 1,322 files. The services group (579 files, 411 code files) is the largest and contains the core meeting bot API, meeting transcription API, and MCP server for AI agents. It supports auto-join bots, real-time WebSocket transcripts across 100+ languages via Whisper, interactive bots that can speak/chat/share screen, and a browser bot layer using CDP + Playwright with persistent authenticated sessions via S3. The packages group (46 files) includes the transcript-rendering library and vera-cli. The libs group (9 files) holds admin models and schema-sync utilities. The tests3 group (188 files) and scripts group (4 files) complete the portfolio.

Three substantial projects stand out: the meeting API service, the Vera bot core, and the transcript-rendering package. The remaining groups are smaller utilities, test infrastructure, and deployment scripts.

How It Is Wired

Execution originates from the CLI entry points: packages/vexa-cli/vexa_cli/main.py and packages/vexa-client/setup.py. The meeting API service (services/meeting-api/meeting_api/main) is the primary inbound gateway, handling inbound webhooks from meeting platforms and orchestrating bot deployment. Control flows through services/vexa-bot/core/src/index.ts (instability 0.81, in a circular import cycle with 6 modules depending on it and 26 it imports), which serves as the central hub—46 modules depend on this file, making it a high-blast-radius point of change. The types module (services/vexa-bot/core/src/types) is imported by 26 modules with zero instability, indicating it remains relatively stable despite the hub's volatility.

The import graph contains 21 modules inside circular dependencies, notably services/vexa-bot/core/src/utils.ts, services/vexa-bot/core/src/platforms/shared/meetingFlow.ts, and services/vexa-bot/core/src/index.ts. Oversized files contribute to cognitive load: services/vexa-bot/core/src/index.ts contains 1,849 lines of code across max indentation depth 9, and services/meeting-api/meeting_api/schemas.py and services/meeting-api/meeting_api/meetings.py share this burden. Broad exception handling without specificity appears in services/meeting-api/meeting_api/meetings.py, post_meeting.py, and container_stop_outbox.py. Duplicate 6-line blocks repeat 1,242 times across 161 files, particularly in deployment scripts under deploy/.

How To Use It

Setup: The repository uses npm as package manager ( evidenced by packages/transcript-rendering/package.json and package-lock.json). Python dependencies are managed via pyproject.toml files in libs/ and deploy/lite/requirements.txt. Docker is supported via deploy/lite/Dockerfile.lite and docker-compose files under deploy/compose/. No single root-level install command exists because this is a portfolio of projects; each sub-project requires its own dependency resolution.

Configuration: Environment variables and keys are expected in deploy/env-example. The Helm charts under deploy/helm/charts/ provide the primary deployment path, with separate charts for the full Vera platform (vexa) and the lightweight variant (vexa-lite). Database migrations and schema sync are handled through libs/admin-models/pyproject.toml and libs/schema-sync/pyproject.toml.

Running it: The CLI entry point is packages/vexa-cli/vexa_cli/main.py. For Docker-based deployment, deploy/compose/docker-compose.yml orchestrates the full stack. A lightweight mode is configured in deploy/lite/Dockerfile.lite and its accompanying Makefile. No single make run or npm start at the root level covers the entire system.

Real-World Use

A practical workflow: a product team integrates the meeting bot API by generating a scoped API token through the admin models, then uses the MCP server to have an AI agent join scheduled meetings, read real-time WebSocket transcripts, and surface action items. The browser bot layer can capture screen content for visual context. All transcripts and recordings stay within the self-hosted infrastructure. For example, a team might run docker-compose up -d from deploy/compose/ to bring up the meeting API, Redis, MinIO for storage, and the dashboard UI, then authenticate via the generated token to start bot sessions.

Code Health & Issues

The static analysis of 570 code files surface 205 findings across 7 categories:

Import cycles affect 21 modules, primarily in services/vexa-bot/core/src/—utils.ts, meetingFlow.ts, and index.ts participate in circular dependencies that increase rebuild time and obscure dependency boundaries.
Hub module services/vexa-bot/core/src/utils.ts is depended on by 46 other modules; changes here ripple broadly.
Deep nesting (max depth 9) and oversized files (1,849 lines) in services/vexa-bot/core/src/index.ts, services/meeting-api/meeting_api/schemas.py, and services/meeting-api/meeting_api/meetings.py make control flow hard to follow.
Broad exception handling in services/meeting-api/meeting_api/meetings.py, post_meeting.py, and container_stop_outbox.py swallows errors indiscriminately.
High branching density (68 branch points over 205 lines) in services/vexa-bot/core/src/platforms/shared/meetingFlow.ts and index.ts suggests decision logic that would benefit from strategy dispatch.
Duplicated code: 1,242 repeated 6-line blocks across 161 files, primarily in deployment scripts under deploy/compose/scripts/ and deploy/lite/.

Beyond these measured findings, the repository hygiene is sound: tests and GitHub Actions CI are present, Dockerfiles exist, the Apache 2.0 license is committed, and lockfiles are present where expected. No committed secrets were detected.

The Bottom Line

Vexa is a capable self-hosted meeting transcription and bot control platform that hits the mark for teams requiring data sovereignty across Google Meet, Teams, and Zoom. The codebase shows its age and scope through circular imports, oversized files, and duplicated deployment logic—issues expected in a project that started as a startup open-source release and grew organically. Teams with strong DevOps discipline can mitigate the health findings through the provided fixes. It's best suited for organizations that want to run their own meeting infrastructure rather than pay per-seat SaaS fees, and who have the engineering capacity to maintain a moderately complex Node/Python hybrid system. If you need a turnkey SaaS alternative, look elsewhere; if you need to self-host and tinker, Vexa is a solid starting point.