Operations

This chapter covers running LiteBot day to day: where the logs are, what NODE_ENV changes, which health probes to poll, how language model providers fail and recover, what a restart does, how Redis fits in, what reloads without a restart, capacity, backups and a safe deploy routine. It assumes the binary under pm2 from Quickstart: binary.

Logs

LiteBot logs through winston. Every line goes to standard output, so pm2 captures it. With NODE_ENV=production, LiteBot also writes log files under the working directory.

Console lines are coloured and look like info: POST /api/chat 200 812ms {...}. Every HTTP request gets one such line with method, path, status and duration. Grep on the words, not on the line start.

pm2 logs litebot --lines 200 --nostream | grep -E "error|unhealthy|Circuit breaker"

Lines worth knowing:

What NODE_ENV changes

NODE_ENV defaults to development when unset. Many installations keep it at development because production mode switches off the reload endpoints and tightens the rate limit. Decide deliberately:

API_RATE_LIMIT replaces the request count in either mode; the window stays 5 or 15 minutes. The limit applies to all /api routes except /api/documents and /api/collections, and it counts per client address (trust proxy is set to one hop, so behind a reverse proxy it uses X-Forwarded-For). A voice gateway or a WhatsApp integration sends all its traffic from one address: in production mode, raise API_RATE_LIMIT well above its peak turns per 15 minutes, or its requests get HTTP 429. WebSocket traffic is not rate limited.

Health probes

LiteBot creates the four required collections at boot, so /health/ready fails only when the database or the auto-dialer is broken.

curl -s http://127.0.0.1:3345/health/detail -H 'Authorization: Bearer <token>'

{
  "status": "healthy",
  "timestamp": "2026-10-24T07:19:33.032Z",
  "uptime": 86234.5,
  "environment": "development",
  "version": "1.0.0",
  "services": {
    "mongodb": "healthy",
    "redis": { "status": "disabled", "message": "Redis not available - using memory fallback", "connected": false },
    "vectorDb": { "provider": "vectra", "status": "healthy" },
    "autoDialer": { "initialized": false, "enabled": false, "lastError": null, "initializedAt": null }
  }
}

Poll /health every 30 to 60 seconds and alert on anything but 200. /health does not test the language model providers: a server whose provider keys are all dead still answers healthy. Watch the provider status below as well, or send a scheduled test chat.

Provider health and recovery

LiteBot tracks each provider registered from .env. After 3 consecutive failed requests it marks the provider unhealthy and logs marked unhealthy. While a provider is unhealthy, a bot that asks for it is served by another healthy provider: DEFAULT_LLM_PROVIDER first, then the others in registration order. This substitution happens even with DISABLE_PROVIDER_FALLBACK=true; that setting only controls the extra fallback attempt made by the circuit breaker. If every provider is unhealthy, LiteBot tries the first registered one anyway. One successful request marks a provider healthy again.

Check the state:

curl -s http://127.0.0.1:3345/api/bots/providers/status -H 'Authorization: Bearer <token>'

{
  "success": true,
  "data": {
    "providers": {
      "gemini": { "healthy": false, "consecutiveFailures": 3, "lastError": "Request failed with status code 402", "provider": "GeminiProvider" },
      "openrouter": { "healthy": true, "consecutiveFailures": 0, "provider": "OpenRouterProvider" }
    },
    "available": ["gemini", "openrouter"],
    "total": 2,
    "healthy": 1
  }
}

Bring a provider back after you fix its key or credit:

curl -s -X POST http://127.0.0.1:3345/api/bots/providers/health-check -H 'Authorization: Bearer <token>'

Newer builds also re-probe an unhealthy provider on their own: once per PROVIDER_RETRY_MS (default 60000), one real request is sent to it, and if it succeeds the provider returns to rotation (log line Probing unhealthy provider <name>). These builds also drop the bot's model name when another provider stands in, logging <name> serving with its default model. In older builds an unhealthy provider stays out until one of the actions above or a restart, and the stand-in provider receives the original bot's model name, which another provider usually rejects. If you run an older build, include the health-check call in your incident routine.

Per-tenant provider keys are outside this rotation: a tenant's own provider never falls back to the global keys. Reinitialising does not re-read .env; edits to .env need a restart. Provider settings are in LLM providers.

Restarts and shutdown

On SIGTERM or SIGINT (what pm2 restart and pm2 stop send), LiteBot closes chat and voice WebSockets, which ends every live voice session, stops its timers and background queue (up to 10 seconds), stops accepting HTTP connections and exits. If that takes longer than 10 seconds it forces the exit. pm2 waits only 1.6 seconds by default before it kills the process; give it the full window:

pm2 delete litebot
pm2 start ./litebot --name litebot --cwd /opt/litebot --kill-timeout 10000
pm2 save

An unhandled error or rejected promise also triggers this shutdown, and pm2 then starts a fresh process. Repeated restarts in pm2 list (the restart counter) point at such errors; read the lines before each Received ... starting graceful shutdown.

What survives a restart: chat sessions and their history, which are stored in MongoDB and reloaded when the next message arrives with the same sessionId. What does not: live voice sessions, in-flight chat turns, the in-memory caches, and provider health state (every provider starts healthy).

Sessions and Redis

Redis is optional. LiteBot always tries to connect to REDIS_HOST:REDIS_PORT (default localhost:6379); if that fails, or after 3 failed reconnect attempts, it logs a warning and uses memory plus MongoDB. Session lookups go through an in-process cache, then Redis when connected, then memory, then MongoDB.

Use Redis when you run more than about 50 concurrent conversations or several LiteBot processes. services.redis.status in /health/detail shows healthy, disabled (not connected) or unhealthy.

Hot reload

Bots and tools edited in the dashboard or through the API apply at once, without a restart. Files on disk and MongoDB edits behave as follows:

Every .js file in config/tools/ is loaded as a tool, except index.js and names starting with . or template. Keep backup copies outside that folder. The admin endpoints POST /api/admin/bots/<botId>/reload and POST /api/admin/prompts/<file>.txt/reload reload one file on demand in either mode. GET /api/admin/hot-reload/status shows whether watching is on.

Capacity

Response time is dominated by the language model and by tool webhooks, not by LiteBot's own processing. One process is one Node.js event loop. Plan memory for the knowledge-base index in Vectra mode, which lives in the process. See Cost and performance.

Backups

mongodump --uri="$MONGODB_URI" --db=litebot --out=/backup/litebot-$(date +%F)

Safe deploy routine

The full steps are in Upgrading. The short checklist:

1. Copy the new binary as litebot.new and the new public/ to the server; compare checksums.
2. Wait for a quiet moment: check pm2 logs litebot for recent POST /api/chat lines and the voice session count (GET /api/voice/stats, authenticated).
3. Back up litebot, public/ and .env with a timestamp suffix.
4. Swap the binary and public/, then pm2 restart litebot --update-env.
5. Check /health, /health/ready, the Loaded N bots and M tools line and the provider status.
6. Send one test chat to a real bot, and watch the logs for ten minutes.
7. If anything is wrong, restore the three backups and restart.

Where to go next

• Fix a symptom: Troubleshooting
• Lock the server down: Security
• Look up a variable: Environment reference
• Review traffic and spend: Conversations and analytics