tutorial

Monitoring Self-Hosted LibreChat with Vigilmon

LibreChat puts every LLM provider behind a single self-hosted interface — but if the Node.js backend, MongoDB, or the RAG pipeline goes down, your team loses AI access entirely. Here's how to monitor every layer of LibreChat with Vigilmon.

LibreChat is the self-hosted ChatGPT alternative that lets you route conversations through OpenAI, Anthropic, Groq, Ollama, and dozens of other LLM providers from a single interface. When it works, it's invisible. When the Node.js backend crashes, MongoDB becomes unavailable, or the RAG pipeline stalls, your entire team loses AI access with no built-in alerting to tell you why. Vigilmon monitors every layer of LibreChat — from the web UI down to the file storage service — so you catch failures before they become support tickets.

What You'll Set Up

  • HTTP uptime monitor for the LibreChat web UI (port 3080)
  • API backend health monitor
  • MongoDB database connectivity heartbeat
  • LLM provider API integration health checks
  • File upload and storage service monitor
  • Cron heartbeat for session authentication service
  • Conversation history service check
  • Plugin execution health monitor
  • RAG pipeline availability monitor
  • Cron heartbeat for scheduled model refresh tasks

Prerequisites

  • LibreChat installed and running (Docker Compose or bare metal)
  • LibreChat accessible at http://your-server:3080 or behind a reverse proxy
  • A free Vigilmon account

Step 1: Monitor the LibreChat Web Interface

The LibreChat React frontend is served by the same Node.js/Express process that handles the API. If either the frontend bundle or the Express server crashes, users see a blank page or a connection error.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your LibreChat URL: https://chat.yourdomain.com (or http://your-server:3080).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Monitor SSL certificate with a 21-day expiry alert if you use HTTPS.
  7. Click Save.

LibreChat's root path returns the React app shell regardless of whether a user is authenticated, making it a clean probe target that won't trigger auth redirects.

Step 2: Monitor the API Backend Health

LibreChat exposes a built-in health endpoint at /api/health. This endpoint confirms the Express server is running and accepting requests — it does not verify downstream dependencies, so use it alongside the service-specific monitors below.

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://chat.yourdomain.com/api/health.
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 1 minute.
  5. Click Save.
# Verify manually
curl https://chat.yourdomain.com/api/health
# {"status":"ok","version":"0.7.x"}

If your LibreChat build does not expose /api/health, check the version-specific docs — older releases used /api/ping or /health.

Step 3: Monitor MongoDB Connectivity

LibreChat stores all user accounts, conversation history, API key configurations, and plugin settings in MongoDB. If MongoDB becomes unavailable, users cannot log in, and existing sessions lose access to conversation history.

MongoDB does not expose an HTTP health endpoint by default, so combine a TCP port monitor with a cron heartbeat.

TCP monitor:

  1. Click Add Monitor → TCP Port.
  2. Set Host to your MongoDB server.
  3. Set Port to 27017.
  4. Set Check interval to 1 minute.
  5. Click Save.

Cron heartbeat for connection-level health:

Add a MongoDB health check script to the LibreChat host:

#!/bin/bash
# mongodb-health.sh
mongosh --quiet --eval "db.adminCommand('ping').ok" \
  "mongodb://localhost:27017/LibreChat" 2>/dev/null | grep -q 1 && \
  curl -s https://vigilmon.online/heartbeat/MONGO_HEARTBEAT_ID

Schedule it:

* * * * * /opt/librechat/scripts/mongodb-health.sh

Create a matching cron heartbeat in Vigilmon with a 1 minute expected interval.

Step 4: Monitor LLM Provider API Integration Health

LibreChat integrates with external LLM APIs (OpenAI, Anthropic, Groq, Ollama). If your API keys expire, provider rate limits are hit, or Ollama's local instance crashes, users get cryptic errors mid-conversation.

For Ollama (local LLM):

Ollama exposes an HTTP API you can probe directly:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to http://your-server:11434/api/tags (returns the list of available models).
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 5 minutes.
  5. Click Save.
# Verify Ollama is running and serving models
curl http://your-server:11434/api/tags
# {"models": [...]}

For external providers (OpenAI, Anthropic, Groq):

These are third-party APIs you can't directly probe, but you can detect failures by watching LibreChat's server logs for provider errors. Add a cron heartbeat tied to a log health script:

#!/bin/bash
# Check LibreChat logs for provider errors in the last 5 minutes
ERROR_COUNT=$(journalctl -u librechat --since "5 minutes ago" 2>/dev/null | \
  grep -c "ECONNREFUSED\|401\|429\|rate limit" || echo 0)

if [ "$ERROR_COUNT" -lt 5 ]; then
  curl -s https://vigilmon.online/heartbeat/LLM_PROVIDER_HEARTBEAT_ID
fi

Step 5: Monitor File Upload and Storage Service

LibreChat supports file uploads for vision models, code interpreters, and RAG document ingestion. Files are stored either locally or in an S3-compatible bucket. If the storage backend is unavailable, file uploads fail silently.

For local storage:

Add a cron heartbeat that checks disk space and write access:

#!/bin/bash
# Check LibreChat uploads directory is writable and not full
UPLOAD_DIR="/path/to/librechat/uploads"
DISK_USAGE=$(df "$UPLOAD_DIR" | awk 'NR==2 {print $5}' | tr -d '%')

if [ "$DISK_USAGE" -lt 90 ] && touch "$UPLOAD_DIR/.health_check" 2>/dev/null; then
  rm -f "$UPLOAD_DIR/.health_check"
  curl -s https://vigilmon.online/heartbeat/STORAGE_HEARTBEAT_ID
fi

For S3-compatible storage (AWS S3, MinIO, Cloudflare R2):

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to your bucket's health endpoint:
    • MinIO: http://minio-host:9000/minio/health/live
    • AWS S3: monitor the LibreChat API's ability to list files via a custom endpoint (add one to your LibreChat config)
  3. Set Check interval to 5 minutes.
  4. Click Save.

Step 6: Monitor User Session Authentication

LibreChat uses JWT tokens stored in MongoDB for session management. If the token signing key is rotated unexpectedly or MongoDB is degraded, all active sessions become invalid and users are logged out.

Create a lightweight health script that validates the auth flow:

#!/bin/bash
# Verify LibreChat auth endpoint responds correctly
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://chat.yourdomain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@invalid.com","password":"invalid"}')

# A 401 response means auth is working (rejecting bad credentials correctly)
if [ "$HTTP_STATUS" -eq 401 ]; then
  curl -s https://vigilmon.online/heartbeat/AUTH_HEARTBEAT_ID
fi

Schedule this every 5 minutes. A 200 response (logged in) or 404/500 indicates a deeper problem.

Step 7: Monitor Conversation History Service

LibreChat's conversation storage can be separately degraded even when the web UI is up — for example if MongoDB write operations are failing while reads still succeed. Monitor conversation write health with a cron heartbeat that checks recent database writes.

On the LibreChat host:

#!/bin/bash
# Check that new conversations are being written to MongoDB
RECENT_WRITES=$(mongosh --quiet --eval \
  "db.conversations.countDocuments({createdAt: {\$gt: new Date(Date.now() - 3600000)}})" \
  "mongodb://localhost:27017/LibreChat" 2>/dev/null)

# If the instance is active, there should be at least some recent writes
# Adjust threshold based on your usage patterns
if [ -n "$RECENT_WRITES" ]; then
  curl -s https://vigilmon.online/heartbeat/CONVO_HEARTBEAT_ID
fi

For a low-traffic instance where the threshold check is unreliable, simply verify MongoDB write latency is acceptable instead.

Step 8: Monitor Plugin Execution Health

LibreChat supports a plugin system that allows execution of tools like web search, code interpreters, and custom APIs. Plugins run as part of the LLM conversation loop — a crashing plugin can hang an entire conversation.

Add an HTTP monitor for LibreChat's plugin list endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://chat.yourdomain.com/api/plugins.
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 5 minutes.
  5. Click Save.

A 200 response confirms the plugin registry is loading correctly. If plugin execution itself fails, you'll typically see it as errors in the LibreChat logs — add the log-watching heartbeat from Step 4 to catch plugin-specific error patterns:

grep -c "plugin.*error\|tool.*failed" /var/log/librechat/app.log

Step 9: Monitor the RAG Pipeline

LibreChat's RAG (Retrieval-Augmented Generation) pipeline allows users to chat with their documents. The pipeline requires a vector database (typically Meilisearch or a local embedding service). If the vector database goes down, RAG-powered conversations return empty or irrelevant context.

For Meilisearch:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to http://your-server:7700/health.
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 1 minute.
  5. Click Save.
curl http://your-server:7700/health
# {"status":"available"}

For pgvector (PostgreSQL extension):

Monitor the parent PostgreSQL instance on port 5432 with a TCP monitor (same pattern as Step 3).

Step 10: Heartbeat for Scheduled Model Refresh

LibreChat periodically refreshes its list of available models from connected providers. If this job stalls, the model selector in the UI can show stale or missing models. Add a cron heartbeat to confirm the refresh task runs successfully.

# Add to crontab - runs every hour to match LibreChat's refresh interval
0 * * * * curl -s https://chat.yourdomain.com/api/models > /dev/null 2>&1 && \
  curl -s https://vigilmon.online/heartbeat/MODEL_REFRESH_HEARTBEAT_ID

Create a cron heartbeat in Vigilmon with a 1 hour expected interval.

Step 11: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and connect Slack or email.
  2. Set Consecutive failures before alert to 2 for the web UI monitor — a single missed check can be a transient network issue.
  3. Set it to 1 for the MongoDB TCP monitor — a database failure always warrants immediate attention.
  4. For Ollama: set Consecutive failures to 3 (Ollama can be slow to respond during model inference).

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://chat.domain.com | Frontend or Express crash | | API health | /api/health | Backend not accepting requests | | MongoDB TCP | :27017 | Database unreachable | | MongoDB heartbeat | Cron ping | Write failures, connection pool exhaustion | | Ollama HTTP | :11434/api/tags | Local LLM not serving models | | LLM provider heartbeat | Log-based cron | External API auth failures, rate limits | | File storage | Storage health endpoint | Uploads failing silently | | Auth heartbeat | Login endpoint returns 401 | Session management broken | | RAG pipeline | Meilisearch /health | Document chat not retrieving context | | Plugin endpoint | /api/plugins | Plugin registry not loading | | Model refresh | Cron heartbeat | Stale model list in UI |

Self-hosting LibreChat means owning the reliability of an AI interface your team depends on. With Vigilmon monitoring every layer — from the Node.js server to the vector database — you'll catch the failures that would otherwise surface as a confused "why isn't the AI working?" support message.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles