The open-source, white-label platform for agencies to build, run and manage AI agents for their clients.
Documentation · Documentación · Quick start · Self-hosting · Discussions
OpenLivery is a multi-tenant workspace where an agency creates AI agents for its clients, gives each client a branded portal, and talks to end users over WhatsApp or an embeddable web chat widget. Bring your own OpenAI / Anthropic keys and self-host the whole thing with one command.
Full documentation lives in docs/. Every guide is written twice: English and Spanish, same filename under each.
| Guide | What it covers |
|---|---|
| Getting started | Run the stack with Docker and create your first agency |
| Configuration | Environment variables, secrets, ports and the gateway |
| Architecture | The services, the data model and tenant isolation |
| Self-hosting | Deploy to a server, back up, upgrade and troubleshoot |
| Contributing | Run the project locally, tests and conventions |
| Push notifications | Optional, provider-agnostic notifications for the mobile app |
| WhatsApp Cloud API | Connect a number with the official Meta API, end to end |
Agents — docs
- ✅ Instructions, personality, per-client & per-agent context, timezone, and temperature / max-tokens / memory controls
- ✅ Multimodal capabilities: image recognition (vision) andaudio transcription for incoming media
- ✅ Creation wizard with a live token counter and industry starter templates
Knowledge base — docs
- ✅ Manual context, structured Q&A pairs and PDF upload, with embedding-based semantic retrieval (keyword fallback)
- ✅ Portable JSON embeddings — no database extension required
AI providers — docs
- ✅ Bring-your-own OpenAI (Responses API) andAnthropic (Messages API) keys — agency-level, encrypted, and validated when saved
- ✅ Any OpenAI-compatible endpoint via per-connection base URL + model
Custom tools — docs
- ✅ Per-agent HTTP tools : any REST endpoint with path/query/body parameters, encrypted auth headers and an SSRF guard
- ✅ MCP servers (Streamable HTTP or SSE) with test-before-save connection checks and cached tool discovery
- ✅ Tool usage recorded per reply and surfaced in the playground, including failure details
Channels — WhatsApp Cloud API · WhatsApp QR · Web widget
- ✅ WhatsApp Cloud API (official Meta API) — bring your own Meta app credentials, signed webhooks, per-client number
- ✅ WhatsApp QR through whatsmeow — QR link, per-client number, persistent session that reconnects on its own
- ✅ Embeddable web chat widget for any website
- 🚧 Instagram DM, Facebook Messenger (planned)
Operations — Inbox · Client portal · Dashboard
- ✅ Unified Inbox with server-side search, filter tabs, unread tracking, pagination and human takeover
- ✅ Per-client portal with its own login and Inbox, optionally served under the client'sown custom domain (DNS-verified, automatic HTTPS)
- ✅ Dashboard with activity, top agents, token usage by model and a date-range filter
- ✅ Agency white-label (name, identifier, color, logo)
Three services plus PostgreSQL, orchestrated by Docker Compose:
| App | Stack | Role |
|---|---|---|
apps/api |
FastAPI · SQLAlchemy · Alembic | REST API, data model, AI/knowledge/provider services |
apps/web |
Next.js · React · TypeScript · Tailwind | Agency dashboard, client portal, playground, widget |
apps/whatsapp |
Go · whatsmeow | WhatsApp Web bridge (stateful sessions) |
All data lives in PostgreSQL; provider keys and WhatsApp sessions are encrypted
at rest. Every query is scoped by agency_id for tenant isolation, and public
endpoints (sign-in and the web widget) are rate-limited per client IP. A Caddy
gateway serves the app and API from a single origin (/api/* → backend).
Read more in the architecture guide.
Requires Docker (Desktop or Engine + Compose plugin).
git clone https://github.com/sarrazola/openlivery.git
cd openlivery
./scripts/generate-docker-env.sh # random secrets in .env.docker (gitignored)
make up # build, start, migrate
Then open http://localhost:3000 (API docs at http://localhost:8000/docs).
Ports clashing? API_PORT=8001 WEB_PORT=3001 DB_PORT=5433 make up.
Prefer not to build? make pull runs the prebuilt images published to GHCR.
The full walkthrough — first agency, provider keys, agents, knowledge and channels — is in the getting started guide. Deploying to a public server (reverse proxy, TLS, backups) is covered in self-hosting.
- GitHub Discussions — questions, ideas and help building with OpenLivery.
- GitHub Issues — bugs and feature requests.
apps/
api/ FastAPI backend (app/, migrations/, tests/)
web/ Next.js frontend (app/, components/, lib/, types/)
whatsapp/ whatsmeow WhatsApp bridge (Go)
mobile/ Optional Expo app for the businesses you serve (unbranded)
docs/ Self-hosting and operations guide
scripts/ Helper scripts (generate-docker-env.sh)
Makefile Common commands (make help)
docker-compose.yml
apps/mobile is an optional Expo app: the inbox a business you serve carries in
their pocket, with conversations, takeover, replies, photos and voice notes. It
is not installed with the platform and the server does not need it — nobody
running OpenLivery has to build or deploy it to have everything working.
It deliberately carries no brand: no name, no logo, no bundle identifier, no preset pointing at any hosted service. What ships is a working app and the machinery to make it yours — put your identity in a brand file, build, and publish it under your own name from your own developer account. The whole checklist, including why you publish it rather than us, is in apps/mobile/WHITELABEL.md.
Run the project locally, the test suites and the conventions are documented in
the contributing guide. In short:
all code, identifiers, comments and docs are in English; end-user UI is localized
(English default, Spanish) through the typed i18n system in apps/web/lib/i18n.
MIT.