LiteBot

LiteBot: Overview

This chapter explains what LiteBot does, how a chat turn and a voice call move through it, what the parts are, and how you run it. Read it first, then follow the link at the end for your setup.

What LiteBot does

LiteBot runs many AI bots from one server. Each bot is a configuration: a system prompt, a language model, a list of tools it may call, and optional voice settings. Your website, WhatsApp integration, phone gateway or own code sends a caller's message to LiteBot; LiteBot picks the bot, keeps the conversation history, asks the language model for a reply, runs any tools the model calls (look up a knowledge base, book an appointment, send a webhook) and returns the answer. Every turn is stored in MongoDB with its tool results, token usage and cost, so you can review conversations and analytics in the dashboard.

Language models are pluggable. LiteBot ships providers for Groq, OpenRouter, OpenAI, Gemini (AI Studio and Vertex AI), Sarvam and Ollama, and you choose one per bot. Voice bots can also run on Gemini Live, a realtime speech-to-speech model, through LiteBot's /voice WebSocket.

How a chat turn flows

1. Client sends a message   -> POST /api/chat or WebSocket /chat, with botId and sessionId
2. Bot and session          -> LiteBot loads the bot and the session history
3. Language model           -> the bot's provider writes a reply or asks for a tool
4. Tools (repeat as needed) -> LiteBot runs the tool, feeds the result back to the model
5. Reply                    -> returned as JSON, or streamed in chunks
6. Record                   -> conversation, cost and trace written to MongoDB

The tool loop in step 4 runs at most REACT_MAX_ITERATIONS times per turn (default 5). Knowledge-base search is a tool too (searchKnowledge in config/tools/knowledge-search.js): the model calls it when the question needs it.

How a voice call flows

1. Caller audio arrives     -> browser or VEXYL gateway opens WebSocket /voice with a key
2. Live session             -> LiteBot opens a Gemini Live session with the bot's prompt, voice and tools
3. Model listens and speaks -> speech in, speech out, in one stream
4. Tools                    -> tool calls from the model run inside LiteBot, results go back to the model
5. Record                   -> transcript, tool results and cost saved as a conversation

Components

Part What it does Required
HTTP API and WebSockets Express server: REST endpoints, /chat and /voice WebSockets, health probes Yes
Providers Connections to the language models, with health tracking and optional fallback At least one API key
Tools JavaScript files in config/tools/, or tools stored in MongoDB No
Knowledge base Uploaded documents, embedded and searched through Vectra (files on disk, the default) or Milvus No
MongoDB Bots, tools, users, tenants, conversations, analytics, leads and tickets Yes
Redis Shared session cache for high load. Without it LiteBot keeps sessions in memory and MongoDB No
Dashboard React web app served from public/: bots, tools, documents, conversations, analytics, users Built in
Modules Visual flow editor and outbound auto-dialer, each switched on by its own setting No

How you run it

LiteBot runs as a single binary, litebot, under the pm2 process manager. The binary contains the server code and its libraries. Beside it, in one directory, you keep:

Item What it is
public/ The dashboard
config/bots/, config/prompts/, config/tools/ Bot files, prompt files and tool files
.env Your settings and API keys
data/, logs/ Knowledge-base vectors and log files, created as needed

The binary itself does not need Node.js on the server; pm2 does. Upgrades swap the binary and public/, and keep everything else. See Quickstart: binary.

What to have ready

  • A Linux x86-64 server. The binary targets node18-linux-x64.
  • A MongoDB database you can reach with a connection string.
  • An API key for at least one language model provider. Voice bots need a Gemini API key (GEMINI_API_KEY).
  • A random secret of at least 32 characters for JWT_SECRET. LiteBot refuses to start without it.
  • Optionally, Redis on the same network.

Working with the VEXYL voice gateway

LiteBot does not answer phone calls by itself. The VEXYL AI Voice Gateway connects to your PBX or SIP trunk and uses LiteBot as the brain, in one of two ways:

Gateway mode What the gateway sends to LiteBot
Speech pipeline The gateway does speech recognition and synthesis, and sends each caller turn as text to POST /api/chat
LiteBot Live (realtime) The gateway forwards the call audio to LiteBot's /voice WebSocket, and LiteBot runs the whole conversation on Gemini Live

The dashboard can also talk to a gateway for browser voice tests (set VEXYL_GATEWAY_WS_URL), and the auto-dialer asks a gateway to place outbound calls. See Voice and Auto-dialer.

Where to go next

Introduction Quickstart: Binary