Installation

Installation Methods

Choose the installation method that best fits your needs:

Docker (Recommended)

Production-ready deployment with all dependencies managed

Local Development

For contributing or custom development work

Docker Installation
Local Development

Docker Installation

Docker is the recommended way to run LibreChat. It handles all dependencies and ensures consistent behavior across systems.

Prerequisites

Install Docker

You need Docker and Docker Compose installed:

Windows
macOS
Linux

Download Docker Desktop for Windows
Run the installer
Restart your computer
Verify installation:

docker --version
docker compose version

Download Docker Desktop for Mac
Drag Docker.app to Applications
Launch Docker Desktop
Verify installation:

docker --version
docker compose version

Install Docker Engine and Docker Compose:

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Verify
docker --version
docker compose version

Log out and back in for group changes to take effect.

Minimum Requirements:

4GB RAM (8GB+ recommended)
10GB disk space
Docker Engine 20.10+ and Docker Compose 2.0+

Clone the Repository

Download LibreChat from GitHub:

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

To install a specific version:

git clone --branch v0.8.3 https://github.com/danny-avila/LibreChat.git

Configuration

Create Environment File

Copy the example environment file:

cp .env.example .env

The .env file contains all configuration options. Key settings:

# Server Configuration
HOST=localhost
PORT=3080
MONGO_URI=mongodb://mongodb:27017/LibreChat

# Security (change these!)
JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418
CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb

# Meilisearch (for conversation search)
MEILI_MASTER_KEY=DrhYf7zENyR6AlUCKmnz0eYASOQdl6zxH7s7MKFSfFCt

Security: Generate new secrets for production:

# Generate secure random strings
openssl rand -hex 32

Replace the default JWT_SECRET, JWT_REFRESH_SECRET, CREDS_KEY, CREDS_IV, and MEILI_MASTER_KEY values.

Configure AI Providers

Add your API keys to .env:

OPENAI_API_KEY=sk-proj-your-key-here
# Or allow users to provide their own:
OPENAI_API_KEY=user_provided

Where to get API keys

OpenAI: platform.openai.com/api-keys
Anthropic: console.anthropic.com
Google AI Studio: aistudio.google.com/apikey
Azure: Requires Azure subscription and OpenAI resource deployment
AWS Bedrock: Enable Bedrock in AWS Console and create IAM credentials

Using custom endpoints (Ollama, LM Studio, etc.)

For local or custom AI providers, create librechat.yaml:

version: 1.3.4
cache: true

endpoints:
  custom:
    # Ollama
    - name: "Ollama"
      apiKey: "ollama"
      baseURL: "http://host.docker.internal:11434/v1"
      models:
        default:
          - "llama3.1:latest"
          - "mistral:latest"
          - "qwen2.5:latest"
      titleConvo: true
      titleModel: "llama3.1:latest"

    # LM Studio
    - name: "LM Studio"
      apiKey: "lm-studio"
      baseURL: "http://host.docker.internal:1234/v1"
      models:
        default:
          - "local-model"

    # Any OpenAI-compatible API
    - name: "Custom API"
      apiKey: "${CUSTOM_API_KEY}"
      baseURL: "https://api.example.com/v1"
      models:
        default:
          - "custom-model-1"

host.docker.internal allows Docker containers to access services on your host machine.

Set User Permissions (Linux)

On Linux, set the user ID and group ID for proper file permissions:

# Add to .env
UID=1000
GID=1000

To find your UID/GID:

echo "UID=$(id -u)"
echo "GID=$(id -g)"

Launch LibreChat

Start Services

Launch all containers:

docker compose up -d

This command:

Downloads required Docker images (LibreChat, MongoDB, Meilisearch, RAG API)
Creates containers and networks
Initializes databases
Starts all services in the background

First run takes 2-5 minutes to download ~2GB of images and initialize databases.

Monitor Startup

Watch the logs to confirm successful startup:

docker compose logs -f

Wait for:

LibreChat | Server listening on port 3080
chat-mongodb | Waiting for connections
chat-meilisearch | MeiliSearch is ready

Press Ctrl+C to exit logs (services continue running).

Access the Application

Open your browser to:

http://localhost:3080

Create your admin account on first visit.

The first registered user becomes the admin. Secure your instance before making it publicly accessible.

Docker Compose Services

The docker-compose.yml file defines these services:

api (LibreChat)

Main application server:

Image: registry.librechat.ai/danny-avila/librechat-dev:latest
Port: 3080
Volumes: .env, images/, uploads/, logs/
Depends on: MongoDB, Meilisearch, RAG API

services:
  api:
    container_name: LibreChat
    ports:
      - "${PORT}:${PORT}"
    image: registry.librechat.ai/danny-avila/librechat-dev:latest
    restart: always
    environment:
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
      - MEILI_HOST=http://meilisearch:7700
    volumes:
      - ./.env:/app/.env
      - ./images:/app/client/public/images
      - ./uploads:/app/uploads
      - ./logs:/app/logs

mongodb

Database for conversations, users, and settings:

Image: mongo:8.0.17
Port: 27017 (internal)
Volume: ./data-node
Command: mongod --noauth

Data persists in ./data-node/ directory.

meilisearch

Full-text search engine for conversations:

Image: getmeili/meilisearch:v1.35.1
Port: 7700 (internal)
Volume: ./meili_data_v1.35.1
Master Key: From MEILI_MASTER_KEY in .env

Powers the conversation search feature (Ctrl+K).

rag_api

RAG (Retrieval-Augmented Generation) API:

Image: registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest
Port: 8000
Depends on: vectordb (PostgreSQL with pgvector)

Handles file processing, embeddings, and vector search for file-based conversations.

vectordb

Vector database for RAG:

Image: pgvector/pgvector:0.8.0-pg15-trixie
Port: 5432 (internal)
Volume: pgdata2

Stores document embeddings for semantic search.

Docker Management

docker compose down

Custom Docker Overrides

To customize Docker Compose without editing the main file:

cp docker-compose.override.yml.example docker-compose.override.yml

Edit docker-compose.override.yml to add custom configurations:

services:
  api:
    environment:
      - CUSTOM_VAR=value
    volumes:
      - ./custom:/app/custom

Docker Compose automatically merges override files.

Local Development Installation

For contributing to LibreChat or custom development work.

Prerequisites

System Requirements

Ensure you have the required software:

Node.js
MongoDB
Meilisearch

Required: Node.js 20.19.0+ or 22.12.0+ or 23.0.0+

# Check version
node --version

# Install Node.js (via nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Or download from nodejs.org

Required: MongoDB 8.0+

macOS
Linux
Windows

brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]

# Ubuntu/Debian
curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-8.0.gpg
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu $(lsb_release -cs)/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl start mongod

Download installer from mongodb.com/try/download/communityOr use Docker:

docker run -d -p 27017:27017 --name mongodb mongo:8.0

Verify MongoDB is running:

mongosh --eval "db.version()"

Required: Meilisearch v1.35.1+

Docker (easiest)
Binary

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:v1.35.1

# macOS
brew install meilisearch
meilisearch --master-key="your-master-key"

# Linux
curl -L https://install.meilisearch.com | sh
./meilisearch --master-key="your-master-key"

Clone Repository

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

Install Dependencies

LibreChat uses npm workspaces for monorepo management:

# Full clean install
npm run reinstall

# Or smart reinstall (only if lockfile changed)
npm run smart-reinstall

This installs dependencies for all workspaces:

/api - Backend server
/client - Frontend React app
/packages/api - TypeScript backend code
/packages/data-provider - Shared data layer
/packages/data-schemas - Database schemas
/packages/client - Shared frontend utilities

Package Manager: LibreChat uses npm 11.10.0+. The packageManager field in package.json enforces this version.

Configuration

Environment Setup

Create your .env file:

cp .env.example .env

Configure for local development:

# Server
HOST=localhost
PORT=3080
MONGO_URI=mongodb://127.0.0.1:27017/LibreChat

# Client
DOMAIN_CLIENT=http://localhost:3080
DOMAIN_SERVER=http://localhost:3080

# Meilisearch
MEILI_HOST=http://localhost:7700
MEILI_MASTER_KEY=your-master-key

# Debug
DEBUG_LOGGING=true
DEBUG_CONSOLE=true

# Security
JWT_SECRET=your-generated-secret
JWT_REFRESH_SECRET=your-generated-secret

# AI Providers
OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=sk-ant-your-key
GOOGLE_KEY=your-key

Build Packages

Build all TypeScript packages:

# Build all via Turborepo (parallel, cached)
npm run build

# Or build sequentially (legacy)
npm run frontend

# Or build specific packages
npm run build:data-provider
npm run build:api
npm run build:client-package

The build script uses Turborepo for intelligent caching and parallel builds.

Running Locally

Start Backend

In one terminal, start the Node.js backend:

npm run backend:dev

This starts the API server with file watching (nodemon). Changes to backend files trigger automatic restart.Backend runs on: http://localhost:3080

Start Frontend

In a second terminal, start the React dev server:

npm run frontend:dev

This starts Vite dev server with HMR (Hot Module Replacement).Frontend runs on: http://localhost:3090

The frontend proxies API requests to the backend at :3080.

Access Application

Open your browser to:

http://localhost:3090

Create your account and start developing!

Development Scripts

npm run backend:dev  # With auto-reload
npm run backend      # Production mode

Project Structure

LibreChat is a monorepo with multiple workspaces:

LibreChat/
├── api/                    # Legacy JS backend server
├── client/                 # React frontend
├── packages/
│   ├── api/               # TypeScript backend (new code goes here)
│   ├── data-provider/     # Shared API client & types
│   ├── data-schemas/      # MongoDB schemas
│   └── client/            # Shared frontend utilities
├── config/                # Configuration scripts
├── e2e/                   # End-to-end tests
├── docker-compose.yml     # Docker services
├── package.json           # Root workspace config
└── .env                   # Environment variables

Development Rule: All new backend code must be TypeScript in /packages/api. Keep changes to /api minimal.

Database Management

npm run create-user      # Create new user
npm run list-users       # List all users
npm run reset-password   # Reset user password
npm run ban-user         # Ban a user
npm run delete-user      # Delete user

Troubleshooting Local Development

MongoDB connection refused

Ensure MongoDB is running:

# Check status
brew services list  # macOS
sudo systemctl status mongod  # Linux

# Start if stopped
brew services start [email protected]  # macOS
sudo systemctl start mongod  # Linux

Verify connection:

mongosh --eval "db.version()"

Port already in use

If ports 3080 or 3090 are in use:

# Find process using port
lsof -i :3080  # macOS/Linux
netstat -ano | findstr :3080  # Windows

# Kill process
kill -9 <PID>

# Or change port in .env
PORT=8080

Build failures

If builds fail:

# Clean install
npm run reinstall

# Clear build cache
rm -rf node_modules/.cache
rm -rf client/node_modules/.cache

# Rebuild
npm run build

Frontend not hot-reloading

If HMR isn’t working:

Check that backend is running on port 3080
Restart frontend dev server
Clear browser cache
Check browser console for errors

Post-Installation

First-Time Setup

Create Admin Account

The first registered user becomes the admin:

Visit http://localhost:3080
Click Sign up
Enter email and password
Register

Subsequent users need to be invited or you must enable public registration.

Configure User Access

Control who can register:

# In .env

# Allow anyone to register
ALLOW_REGISTRATION=true

# Or invite specific users
ALLOW_REGISTRATION=false

Invite users via CLI:

# Docker
docker compose exec api npm run invite-user

# Local
npm run invite-user

Test AI Integration

Verify your AI providers work:

Click the model selector dropdown
Select a provider (OpenAI, Anthropic, etc.)
Choose a model
Send a test message: “Hello!”

If you see errors, check:

API keys are correct in .env
API keys have sufficient credits
Network connectivity to AI providers

Optional Features

Enable web search

Configure search providers in .env:

SEARCH=true

# Search provider (required)
SERPER_API_KEY=your-serper-key

# Scraper (required)
FIRECRAWL_API_KEY=your-firecrawl-key

# Reranker (required - choose one)
JINA_API_KEY=your-jina-key
# or
COHERE_API_KEY=your-cohere-key

Get keys from:

Serper: serper.dev
Firecrawl: firecrawl.dev
Jina: jina.ai

Enable code interpreter

# In .env
LIBRECHAT_CODE_API_KEY=your-key-from-code.librechat.ai

Sign up at code.librechat.ai for API access.Now agents can execute Python, Node.js, Go, Java, PHP, Rust, and Fortran code securely.

Configure file storage

By default, files are stored locally. Configure S3 or Firebase:

AWS S3
Firebase

# In .env
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1
AWS_BUCKET_NAME=librechat-files

# In librechat.yaml
fileStrategy:
  avatar: "s3"
  image: "s3"
  document: "s3"

# In .env
FIREBASE_API_KEY=your-key
FIREBASE_AUTH_DOMAIN=your-app.firebaseapp.com
FIREBASE_PROJECT_ID=your-project
FIREBASE_STORAGE_BUCKET=your-bucket
FIREBASE_MESSAGING_SENDER_ID=your-id
FIREBASE_APP_ID=your-app-id

# In librechat.yaml
fileStrategy:
  avatar: "firebase"
  image: "firebase"
  document: "firebase"

Set up OAuth/SSO

Configure OAuth providers:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-secret
GOOGLE_CALLBACK_URL=/oauth/google/callback

Next Steps

Your LibreChat installation is complete! Here’s what to explore:

Configuration Guide

Deep dive into librechat.yaml and advanced settings

AI Endpoints

Configure all AI providers and custom models

Create Agents

Build custom AI assistants with tools and knowledge

Enable MCP

Add Model Context Protocol servers

User Management

Manage users, roles, and permissions

Production Deployment

Deploy LibreChat to production

Need help?

Join Discord for community support
Check GitHub Discussions
Report issues on GitHub

Get Started

Core Features

Configuration

Deployment

User Guide

Administration

Installation Methods

Docker (Recommended)

Local Development

Docker Installation

Prerequisites

Configuration

Launch LibreChat

Docker Compose Services

Docker Management

Custom Docker Overrides

Local Development Installation

Prerequisites

Configuration

Running Locally

Development Scripts

Project Structure

Database Management

Troubleshooting Local Development

Post-Installation

First-Time Setup

Optional Features

Next Steps

Configuration Guide

AI Endpoints

Create Agents

Enable MCP

User Management

Production Deployment

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

User Guide

Administration

​Installation Methods

Docker (Recommended)

Local Development

​Docker Installation

​Prerequisites

​Configuration

​Launch LibreChat

​Docker Compose Services

​Docker Management

​Custom Docker Overrides

​Local Development Installation

​Prerequisites

​Configuration

​Running Locally

​Development Scripts

​Project Structure

​Database Management

​Troubleshooting Local Development

​Post-Installation

​First-Time Setup

​Optional Features

​Next Steps

Configuration Guide

AI Endpoints

Create Agents

Enable MCP

User Management

Production Deployment

Build docs developers (and LLMs) love

Installation Methods

Docker Installation

Prerequisites

Configuration

Launch LibreChat

Docker Compose Services

Docker Management

Custom Docker Overrides

Local Development Installation

Prerequisites

Configuration

Running Locally

Development Scripts

Project Structure

Database Management

Troubleshooting Local Development

Post-Installation

First-Time Setup

Optional Features

Next Steps