LiteBot

Environment reference (2 of 2): chat, tools, voice, modules, analytics

This page lists the environment variables that shape conversations, tools, voice sessions, the optional modules, analytics and logging. Use it with part 1, which covers the server, security, data stores, providers and the knowledge base: Environment reference (1 of 2).

  • Put the variables in the .env file beside dist/litebot (the directory pm2 starts it in) and restart the process after a change.
  • Default is the value the code uses when the variable is unset or empty. unset means there is none. Where the sample .env.example sets a different value, the Meaning column says so.
  • A switch that is off by default is turned on only by the exact text true; one that is on by default is turned off only by false. Exceptions are noted.
  • For a number, 0 counts as unset and the default applies, unless the row gives 0 its own meaning. Several voice limits have no off value for this reason.

Chat and conversation behaviour

Variable Default Meaning
REACT_MAX_ITERATIONS 5 Most tool-call rounds in one turn. Raise it only for bots that chain many tools.
FLOW_MAX_AUTO_ADVANCE REACT_MAX_ITERATIONS, else 10 Most non-LLM nodes a visual-flow bot moves through in one turn (Visual flows).
LLM_HISTORY_MAX_MESSAGES 40 Messages of history sent to the model, cut on a user-turn boundary. Fewer means fewer input tokens per call.
MAX_SESSION_MESSAGES 200 Messages kept per session; older ones are dropped from the stored transcript.
MAX_MESSAGE_LENGTH 4000 Longest inbound chat message in characters. Longer messages are rejected.
SESSION_IDLE_TIMEOUT_MS 1800000 A session idle this long (30 minutes) is ended by the sweep, which also runs its session-end hooks.
SESSION_CLEANUP_INTERVAL_MS 900000 How often that sweep runs (15 minutes).
STREAM_HOLD_TOOL_TURNS on For bots with tools, streamed text is held per LLM call and only the call that ends the turn is sent, so a voice gateway never speaks interim text that a tool result then corrects. false streams every token at once: faster first audio, but callers can hear the uncorrected text. Bots without tools always stream every token. Read on every turn.
ENABLE_MESSAGE_QUEUE off Write conversation batches to MongoDB through a background queue instead of in line. Required by the auto-dialer. The sample turns it on.
MESSAGE_QUEUE_WORKERS 4 Queue workers.

See Chat API and Bots.

Tools

Variable Default Meaning
TOOL_EXECUTION_TIMEOUT 5000 Timeout for one tool call, ms. A tool's metadata.timeout wins. Enforced only when ENABLE_CIRCUIT_BREAKER=true, and replaced by CIRCUIT_BREAKER_TIMEOUT when that is set.
ENABLE_TOOL_CACHE on Cache results of tools whose metadata.cacheable is true.
TOOL_CACHE_MAX_SIZE 500 Cached tool results. Replaced by APP_CACHE_MAX_SIZE when that is set.
TOOL_CACHE_DEFAULT_TTL 300 Seconds a result is cached when the tool sets no metadata.cacheTTL.
TOOLS_DB_POLL_MS 15000 How often tools stored in MongoDB are re-read, so dashboard edits on another process show up. 0 or a negative value turns polling off.
ENABLE_HOT_RELOAD off in production true makes LiteBot pick up edits to bot files in config/bots without a restart. With NODE_ENV other than production it is always on and tool files in config/tools are watched too (dev-only); in production tool files are never watched, so restart after editing one.
TOOL_GENERATOR_MODEL llama-3.3-70b-versatile Model used by the dashboard's AI tool generator.
BOT_GENERATOR_MODEL llama-3.3-70b-versatile Model used by the dashboard's AI bot generator.

Caches and circuit breaker

Variable Default Meaning
ENABLE_CIRCUIT_BREAKER off Turns on the circuit breaker around every LLM and tool call. It also enforces the timeouts: with it off, LLM and tool calls run without LiteBot's timeout. The sample turns it on.
CIRCUIT_BREAKER_THRESHOLD 5 Failures in a row before a breaker opens and calls are refused for a minute (30 seconds for tools).
CIRCUIT_BREAKER_TIMEOUT unset When set, the timeout for every breaker, replacing LLM_REQUEST_TIMEOUT, TOOL_EXECUTION_TIMEOUT and each tool's metadata.timeout. The sample sets 30000. Leave it unset to keep per-tool timeouts.
ENABLE_APP_CACHE off The session look-up cache in front of MongoDB.
APP_CACHE_MAX_SIZE 100 Entries in the session cache. When set, it is also the size of every other in-process cache: tool results, API keys and roles.
APP_CACHE_TTL 300 Seconds entries live in the session cache. When set, it is also the lifetime in the API-key and role caches, replacing API_KEY_CACHE_TTL and ROLE_CACHE_TTL.

See Tools.

Voice

These apply to Gemini Live sessions on /voice. A bot's voice.* settings win where both exist. See Voice.

Variable Default Meaning
GEMINI_LIVE_MODEL gemini-3.1-flash-live-preview Default Live model; a bot's voice.model wins. Needs GEMINI_API_KEY (or a tenant Gemini key).
MAX_VOICE_SESSIONS_CONCURRENT 10 Voice sessions per LiteBot process.
MAX_VOICE_SESSIONS_PER_USER 1 Sessions at once per dashboard (JWT) user.
API_KEY_DEFAULT_MAX_VOICE_CONCURRENT 50 Sessions at once per API key, unless the key's own record sets a limit.
MAX_VOICE_SESSION_DURATION_MS 900000 Longest session (15 minutes). 0 does not disable it.
VOICE_SESSION_IDLE_TIMEOUT_MS 300000 A session with no frames for this long is closed.
VOICE_SILENCE_TIMEOUT_MS 30000 A session with no speech, text or tool call for this long is ended; silent audio frames do not count. 0 does not disable it.
VOICE_SILENCE_CHECK_INTERVAL_MS 5000 How often silence is checked.
VOICE_WS_PING_INTERVAL_MS 30000 WebSocket ping interval.
VOICE_WS_PING_MAX_MISSED 2 Missed pongs before the connection is dropped.
VOICE_AUDIO_BYTES_PER_SEC 262144 Inbound audio rate limit per session.
VOICE_AUDIO_TOTAL_BYTES_CAP 104857600 Total inbound audio per session (100 MB).
VOICE_SESSION_TOKEN_TTL_MS 3300000 Lifetime of the short-lived token a voice session uses for tool calls (55 minutes).
VOICE_INPUT_MIME_TYPE audio/pcm;rate=16000 Inbound audio format. Gemini Live accepts only a few PCM rates.
VOICE_TURN_COVERAGE unset TURN_INCLUDES_ONLY_ACTIVITY or TURN_INCLUDES_ALL_INPUT. Unset uses Gemini's default.
VOICE_THINKING_BUDGET 0 Model thinking for voice. 0 is off and gives the fastest replies; -1 lets the model decide.
VOICE_VAD_SILENCE_MS unset Silence in ms that ends the caller's turn. Unset uses Gemini's default. The sample sets 800.
VOICE_VAD_PREFIX_PADDING_MS unset Speech in ms needed before it counts as the start of a turn. The sample sets 300.
VOICE_VAD_START_SENSITIVITY unset START_SENSITIVITY_HIGH (easier to interrupt the bot) or START_SENSITIVITY_LOW.
VOICE_VAD_END_SENSITIVITY unset END_SENSITIVITY_LOW (waits longer before cutting the caller off) or END_SENSITIVITY_HIGH.
VOICE_VAD_DISABLED off Turns off automatic turn detection; the client must signal turns.
VOICE_MAX_LLM_CONTEXT_CHARS 0 Cap on the caller-supplied context added to the prompt. 0 is unlimited. Set a cap when untrusted clients can open voice sessions.
VOICE_MAX_LLM_CONTEXT_VALUE_CHARS 0 Cap per value inside that context. 0 is unlimited.
VOICE_TEXT_INPUT_MAX_CHARS 0 Longest text_input frame; longer frames are rejected. 0 is unlimited.
VOICE_USAGE_CUMULATIVE off How Gemini's usage frames are added up for cost. Off sums every frame. Change it only if the voice usage log lines show steadily rising totals.

Modules

Auto-dialer

Variable Default Meaning
ENABLE_AUTO_DIALER off Turns on outbound campaigns. Needs ENABLE_MESSAGE_QUEUE=true.
AUTO_DIALER_OUTBOUND_ENDPOINT unset Gateway endpoint that places calls. A campaign's own setting wins, then the dashboard setting, then this.
AUTO_DIALER_PUBLIC_URL unset Public base URL the voice gateway uses to report each call's progress. It must be reachable from the gateway. Unset means no tracking: a contact counts as completed as soon as the gateway accepts the call.
AUTO_DIALER_WEBHOOK_SECRET JWT_SECRET Signs the per-call callback URLs. The older webhook /api/campaigns/webhook/:campaignId checks a signature only when this is set.
AUTO_DIALER_INITIATE_TIMEOUT_MS 90000 Wait for the gateway's call request. It returns only after the callee answers, so keep this above the ring time.
AUTO_DIALER_MAX_CALL_SECONDS 900 A call slot is released after this long if no final status arrives.
AUTO_DIALER_FAILURE_TTL 86400 Seconds the consecutive-failure counter of a campaign is kept.

See Auto-dialer.

Visual editor and gateway voice mode

Variable Default Meaning
ENABLE_VISUAL_EDITOR off Shows the visual flow editor in the dashboard (Visual flows).
VEXYL_GATEWAY_WS_URL unset wss:// address of a VEXYL voice gateway whose LiteBot brain points at this server. Turns on the dashboard's Gateway voice mode. Must start with ws:// or wss://.
VEXYL_GATEWAY_API_KEY unset Key for that gateway. Logged-in dashboard users can see it in the browser.
VEXYL_GATEWAY_TTS_PROVIDER unset Voice provider the gateway should use in that mode. Unset uses the gateway's own default.

Analytics and logging

Variable Default Meaning
ENABLE_REQUEST_TRACING on Writes a request_traces record of LLM calls and tool calls. Only the exact text false turns it off.
ANALYTICS_TZ Asia/Kolkata Timezone for daily and hourly report buckets. A request can override it with ?tz=.
ANALYTICS_BATCH_SIZE 50 request_analytics rows queued before they are written.
ANALYTICS_BATCH_INTERVAL_MS 2000 Longest wait before queued rows are written.
ANALYTICS_MAX_REQUESTS 1000 Per-call records kept in memory for one active session. Older ones are dropped from the session's running average.
DASHBOARD_AGGREGATE_TIMEOUT_MS 10000 Timeout for each internal call behind GET /api/analytics/dashboard.
LOG_LEVEL debug error, warn, info or debug. Set info in production.
LOG_FILE unset In production, LiteBot writes errors to logs/error.log and everything to logs/combined.log. Setting LOG_FILE sends both to that one file. Console output always goes to pm2's log.

See Conversations and analytics.

Diagnostic switches

Leave these unset unless you are tracing a fault.

Variable Meaning
GEMINI_LIVE_DEBUG 1 logs every Gemini Live frame except audio. Only 1 turns it on. Very noisy.
VOICE_DUMP_INBOUND_WAV 1 or true saves the first seconds of each voice session's inbound audio as a WAV file, to hear what the model received.
VOICE_DUMP_INBOUND_SECONDS Seconds saved; default 5.
VOICE_DUMP_DIR Where the WAV files go; default /tmp.

Where to go next

Environment (1 of 2) Cost and Performance