LiteBot

Environment reference (1 of 2): server, security, data stores, providers, knowledge base

This page lists the environment variables LiteBot reads for the server itself, sign-in and security, MongoDB and Redis, the LLM providers and the knowledge base. Use it when you set up .env or when a chapter tells you to change a setting. Part 2 covers chat behaviour, voice, tools, modules and analytics: Environment reference (2 of 2).

  • Put the variables in the .env file in the directory pm2 starts dist/litebot from, normally beside the binary. LiteBot reads it once at start-up; restart the process after a change (pm2 restart litebot).
  • Default is the value the code uses when the variable is unset or empty. unset means there is none. Booleans show as on or off. 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. A switch that is on by default is turned off only by the exact text false.
  • For a number, 0 usually counts as unset and the default applies. The rows say where 0 has its own meaning.
  • Relative paths (./data/vectra, logs/...) are resolved from the directory pm2 starts the binary in.
  • Dev-only marks behaviour you get only with NODE_ENV other than production. Run the binary with NODE_ENV=production.

Server

Variable Default Meaning
PORT 3000 HTTP and WebSocket port. The sample and this manual use 3345.
NODE_ENV development Set production. It selects the stricter rate-limit window, file logging, generic error messages and no hot reload. Any other value is dev-only behaviour: stack traces in error replies, bot and tool file watching, a 5-minute rate-limit window.
SERVER_LISTEN_TIMEOUT_MS 5000 Start-up is aborted if the port has not been bound within this many ms.
CSP_CONNECT_ORIGINS unset Comma-separated origins added to the dashboard's Content-Security-Policy connect-src. 'self', ws: and wss: are always allowed. Needed when the dashboard talks to another host, such as a voice gateway.
DEFAULT_BOT_ID unset Bot used when a request names no bot and intent detection finds no match. A loaded bot with id default is used first; this variable is the next choice. It must match a loaded bot id.
BOT_TZ server timezone IANA zone for the "current date" line LiteBot gives every bot, for example Asia/Kolkata. Analytics uses ANALYTICS_TZ instead.

Authentication and security

Variable Default Meaning
JWT_SECRET unset Required. At least 32 characters or LiteBot refuses to start. Signs dashboard logins and also keys the encryption of stored provider credentials, so changing it logs everyone out and makes stored tenant keys unreadable.
JWT_EXPIRES_IN 24h Lifetime of a login token.
API_RATE_LIMIT 100 in production, 500 otherwise Requests per IP per window on /api. The window is 15 minutes in production, 5 minutes otherwise (dev-only). /api/collections and /api/documents are exempt. A voice gateway that sends all its calls from one IP counts as one client, so size this for it.
ADMIN_USERNAME admin Bootstrap admin login, used only when no dashboard user exists in MongoDB.
ADMIN_PASSWORD_HASH unset scrypt salt:hash (hex) for that login. Unset disables the bootstrap login.
API_KEY_CACHE_TTL 60 Seconds a verified lbk_ API key stays cached, so repeat traffic skips the slow hash check. Ignored when APP_CACHE_TTL is set (see below).
API_KEY_FAIL_LIMIT 20 Bad API keys allowed from one IP inside the window before further attempts are refused without checking.
API_KEY_FAIL_WINDOW_MS 60000 That window, in ms.
ROLE_CACHE_TTL 30 Seconds a role's permission list is cached. Ignored when APP_CACHE_TTL is set.
ALLOWED_TEMPLATE_ENV_VARS NODE_ENV,APP_NAME,SITE_URL,SUPPORT_EMAIL Variables a bot template may read as {{env.NAME}}. Anything not listed is left unresolved, so bot configs cannot read secrets.

APP_CACHE_TTL and APP_CACHE_MAX_SIZE (part 2) apply to every in-process cache, and when set they win over the cache's own setting. With APP_CACHE_TTL=300 the API-key and role caches keep entries for 300 seconds, not 60 and 30. Leave APP_CACHE_* unset if you want API_KEY_CACHE_TTL and ROLE_CACHE_TTL to apply.

See Security and Users, roles and tenants.

MongoDB

Variable Default Meaning
MONGODB_URI mongodb://localhost:27017/bitvoice_bot Connection string. Required in practice.
MONGODB_DB_NAME bitvoice_bot Database name.
MONGODB_MAX_POOL_SIZE 50 Largest connection pool.
MONGODB_MIN_POOL_SIZE 5 Connections kept open.
MONGODB_CONNECTION_TIMEOUT 5000 Connect timeout, ms.
MONGODB_ENABLE_COMPRESSION off Compress traffic to MongoDB. The sample turns it on.
MONGODB_COMPRESSION_LEVEL 6 Compression level when compression is on.
MONGODB_READ_PREFERENCE nearest Read preference for replica sets.
MONGODB_JOURNAL on Wait for the journal on writes. false acknowledges earlier, at some risk on a crash.

Redis

Redis is optional. LiteBot always tries to connect; if Redis is not reachable it carries on with in-memory sessions and caches.

Variable Default Meaning
REDIS_HOST localhost Redis server.
REDIS_PORT 6379 Redis port.
REDIS_PASSWORD unset Redis password.
REDIS_DB 0 Database number.
REDIS_WRITE_THROUGH off Write sessions to Redis first and to MongoDB in the background. Use it when several LiteBot processes share sessions. The sample turns it on.
REDIS_SESSION_TTL 3600 Seconds a session stays in Redis.

LLM providers

A provider is registered only when its key (or, for Ollama and Vertex, its settings) is present. Bots pick a provider and model in their own config; the *_MODEL values below apply when a bot names none. See LLM providers.

Selection, timeouts and failover

Variable Default Meaning
DEFAULT_LLM_PROVIDER unset Provider used when a bot's provider is missing or unhealthy, and first choice for failover. Unset uses registration order: groq, openrouter, gemini, openai, sarvam, ollama.
DISABLE_PROVIDER_FALLBACK off true stops failover to another provider. Recommended: other providers do not know your bot's model name. Tenant-keyed providers never fail over.
LLM_REQUEST_TIMEOUT 30000 Timeout for one LLM call, ms. Ollama's built-in default is 120000. Enforced through the circuit breaker, so only with ENABLE_CIRCUIT_BREAKER=true.
<PROVIDER>_REQUEST_TIMEOUT unset Per-provider override of LLM_REQUEST_TIMEOUT. The name is the provider upper-cased with other characters turned into _: GEMINI_REQUEST_TIMEOUT, GEMINI_VERTEX_REQUEST_TIMEOUT, OLLAMA_REQUEST_TIMEOUT.
PROVIDER_RETRY_MS 60000 After a provider is marked unhealthy, how long until it is tried again.

Groq, OpenRouter, OpenAI, Sarvam

Variable Default Meaning
GROQ_API_KEY unset Registers Groq.
GROQ_MODEL llama-3.3-70b-versatile Default Groq model.
OPENROUTER_API_KEY unset Registers OpenRouter.
OPENROUTER_MODEL meta-llama/llama-3.1-70b-instruct Default OpenRouter model.
OPENROUTER_APP_NAME Bitvoice AI App name sent to OpenRouter.
OPENROUTER_SITE_URL https://bitvoice.ai Site URL sent to OpenRouter. Set your own.
OPENROUTER_SORT unset Endpoint routing: price, throughput or latency. Unset uses OpenRouter's load balancing.
OPENROUTER_IDLE_TIMEOUT_MS 30000 Abort a stream that sends nothing for this long.
OPENAI_API_KEY unset Registers OpenAI. Also enables OpenAI embeddings.
OPENAI_MODEL gpt-4-turbo-preview Default OpenAI model.
OPENAI_ORGANIZATION unset OpenAI organisation id.
OPENAI_SERVICE_TIER auto auto, default, flex (cheaper, slower) or priority.
SARVAM_API_KEY unset Registers Sarvam.
SARVAM_MODEL sarvam-30b Default Sarvam model.

Gemini (AI Studio and Vertex AI)

Variable Default Meaning
GEMINI_API_KEY unset Registers gemini (AI Studio). Also needed for voice sessions and enables Gemini embeddings.
GEMINI_MODEL gemini-1.5-flash Default model for gemini. That model is retired, so set it, keeping the models/ prefix: models/gemini-2.5-flash.
GEMINI_CACHE_ENABLED on Context caching of each bot's system prompt and tools. Cached tokens are billed at the cache rate. false turns it off.
GEMINI_CACHE_TTL 3600s Lifetime of a cache entry.
GEMINI_CACHE_MIN_TOKENS 2048 Skip caching when the prompt and tools are shorter than this; Gemini rejects small caches.
GEMINI_HEDGE_DELAY_MS 6000 If no first token arrives in this many ms, send a duplicate request and keep whichever answers first. Guards against rare long stalls. 0 turns it off. Keep it well above your normal first-token time or you pay twice for many calls.
VERTEX_PROJECT_ID unset Google Cloud project. With a credentials file, registers gemini-vertex.
VERTEX_LOCATION asia-south1 Vertex region, or global. A model the region does not serve is retried once on global.
VERTEX_CREDENTIALS_FILE unset Path to the service-account JSON key. Falls back to GOOGLE_APPLICATION_CREDENTIALS.
GOOGLE_APPLICATION_CREDENTIALS unset Standard Google fallback for the key file.
VERTEX_MODEL GEMINI_MODEL, else models/gemini-2.5-flash Default model for gemini-vertex.

Ollama

Variable Default Meaning
OLLAMA_ENABLED off Registers Ollama. Setting OLLAMA_BASE_URL also registers it.
OLLAMA_BASE_URL http://localhost:11434 Ollama server.
OLLAMA_MODEL llama3.2 Default model. It must support tool calling.
OLLAMA_REQUEST_TIMEOUT 120000 Request timeout, ms. Cloud models start slowly.
OLLAMA_API_KEY unset Bearer token for Ollama Cloud or an authenticated proxy.
OLLAMA_KEEP_ALIVE 30m How long Ollama keeps the model loaded.
OLLAMA_THINKING off Thinking mode on models that support it.
ALLOW_LOCAL_OLLAMA on Lets an Ollama URL on a private or local address pass the dashboard's address check. false applies the public-host rule to Ollama too.

Embeddings

Embeddings turn knowledge-base text and search queries into vectors. Changing to a provider with a different vector size means re-indexing your documents. See Knowledge base.

Variable Default Meaning
EMBEDDINGS_PROVIDER auto gemini, openai, huggingface or local. Unset, or a provider without a key, picks the first available in that order.
GEMINI_EMBED_MODEL gemini-embedding-001 Gemini embedding model. Must match your existing index.
GEMINI_EMBED_DIMENSION 768 Vector size. Must match your existing index.
GEMINI_EMBED_TRANSPORT Vertex when VERTEX_* is set aistudio forces the API-key route. Both give identical vectors.
GEMINI_EMBED_BATCH 100 Texts per Vertex request when indexing.
GEMINI_EMBED_TIMEOUT 15000 Vertex embedding timeout, ms.
HUGGINGFACE_API_KEY unset Registers Hugging Face embeddings (384-dimension vectors).
EMBED_BATCH_SIZE 64 Documents per embedding request when indexing, all providers.
EMBED_CACHE_ENABLED on In-memory cache of query embeddings (exact text matches).
EMBED_CACHE_MAX_SIZE 5000 Entries in that cache.

Vector database

Variable Default Meaning
VECTOR_DB_PROVIDER milvus vectra (files on disk, no extra service) or milvus. The sample sets vectra; set it explicitly, because the code default is milvus.
VECTRA_DATA_PATH ./data/vectra Where Vectra keeps its index files. Back this directory up.
MILVUS_ADDRESS unset Milvus or Zilliz Cloud address.
MILVUS_USERNAME unset Milvus user.
MILVUS_PASSWORD unset Milvus password.
MILVUS_DATABASE default Milvus database.
VECTOR_CACHE_ENABLED off Cache search results. The sample turns it on. Legacy name MILVUS_CACHE_ENABLED.
VECTOR_CACHE_TTL 3600 Seconds a cached search result is kept. Legacy name MILVUS_CACHE_TTL.
VECTOR_CACHE_MAX_SIZE 1000 Cached search results. The query-embedding cache inside the vector manager reads the same variable with its own default of 2000. Legacy name MILVUS_CACHE_MAX_SIZE.
VECTOR_CACHE_TTL_MS 300000 Lifetime of entries in that query-embedding cache, ms.
VECTOR_SEARCH_TIMEOUT 3000 Search timeout, ms. Legacy name MILVUS_SEARCH_TIMEOUT.
VECTOR_PREWARM_ENABLED off Pre-run common searches into the result cache. Legacy name MILVUS_PREWARM_ENABLED.
VECTOR_WARMUP_DISABLED off true skips the start-up warm-up that pre-embeds frequent queries.
VECTOR_WARMUP_QUERIES unset Comma-separated queries to warm up. Unset takes the most frequent queries of the last 7 days.
VECTOR_WARMUP_LIMIT 50 Most queries warmed up.

The MILVUS_* cache names are read only when the matching VECTOR_* name is unset.

Where to go next

Troubleshooting Environment (2 of 2)