TL;DR: LibreChat v0.8.6 takes about 20 minutes to get running via Docker Compose. The payoff is a multi-provider chat interface where you can swap between local Ollama models and any cloud API key — in the same conversation. Local user accounts work out of the box; no OAuth required.

After this guide you’ll have:

• LibreChat running at http://localhost:3080 with a local account
• Ollama connected as a custom endpoint alongside any cloud providers you choose to add
• At least one custom agent with a system prompt and tool access

---

LibreChat is the most feature-complete open-source ChatGPT alternative you can self-host. It supports more providers than anything else in this space — Ollama, OpenAI, Anthropic, Google, Mistral, OpenRouter — from one UI, with per-conversation model switching, agents, plugins, and image generation included.

The catch is setup. LibreChat involves more moving pieces than Open WebUI: Docker Compose with five services, a librechat.yaml config on top of .env, and a few non-obvious steps before you see a working login page. This guide minimizes that friction.

Licensed MIT, active on GitHub with 100K+ stars.

---

What You Need

• Docker Engine 24+ and Docker Compose v2 (not the v1 docker-compose binary — check with docker compose version)
• 4 GB RAM minimum; 8 GB recommended when running local models concurrently
• Ollama installed and running on port 11434 (optional if you’re only using cloud APIs)
• 10 GB free disk space for Docker images and MongoDB data

No GPU is required for LibreChat itself. GPU requirements are determined entirely by the models you run through Ollama.

---

Step 1: Clone and Configure the Environment

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

Open .env and change these fields before anything else:

Security secrets — generate with openssl rand -hex 32:

JWT_SECRET=replace_with_64_char_random_hex
JWT_REFRESH_SECRET=replace_with_different_64_char_hex

Leaving these as placeholder values means anyone who gets the JWT can forge sessions. Takes 10 seconds to fix.

Domain (leave as-is for localhost-only use):

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

Meilisearch key (used for conversation search — required if you enable Meilisearch):

MEILI_MASTER_KEY=another_random_secret

Registration control:

# Set to false once you've created your account
ALLOW_REGISTRATION=true

Cloud API keys (leave empty if not using that provider):

OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...

There is no Ollama API key. Ollama doesn’t require authentication by default.

---

Step 2: Create librechat.yaml

This file lives in the project root alongside docker-compose.yml. It controls custom endpoints (like Ollama), agent configuration, MCP servers, and UI options — anything that doesn’t belong in .env.

Create librechat.yaml:

version: 1.2.0

endpoints:
  custom:
    - name: "Ollama"
      apiKey: "ollama"
      baseURL: "http://host.docker.internal:11434/v1/"
      models:
        default:
          - "llama3.2:latest"
          - "qwen2.5:14b"
          - "mistral:latest"
        fetch: true
      titleConvo: true
      titleModel: "current_model"
      modelDisplayLabel: "Ollama"

Two things matter here:

host.docker.internal is how the LibreChat Docker container reaches Ollama running on your host machine. On Docker Engine 20.10+ for Linux, this works automatically. If it fails, substitute your machine’s LAN IP (192.168.1.x:11434).

fetch: true tells LibreChat to query Ollama’s /api/tags endpoint at startup and list available models dynamically. Without it, you’d manually update the default: list every time you pull a new model.

---

Step 3: Mount the Config via docker-compose.override.yml

LibreChat ships with docker-compose.override.yml.example. Copy it:

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

Open the file and uncomment the librechat.yaml volume mount under the api service:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

This mounts your local config into the container without rebuilding the image. Any edit to librechat.yaml takes effect after docker compose restart api.

If you’re on Linux and Ollama isn’t reachable via host.docker.internal, also add:

services:
  api:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

---

Step 4: Start LibreChat

docker compose up -d

Expected output:

[+] Running 6/6
 ✔ Network librechat_default        Created
 ✔ Container librechat-mongodb-1    Started
 ✔ Container librechat-meilisearch-1 Started
 ✔ Container librechat-vectordb-1   Started
 ✔ Container librechat-rag_api-1    Started
 ✔ Container librechat-api-1        Started

Wait 30–60 seconds on first launch (images download, MongoDB initializes). Open http://localhost:3080.

If the page doesn’t load, check logs:

docker compose logs api --tail 50

Common first-launch errors:

Error	Cause	Fix
MongoServerError: Connection refused	MongoDB not ready yet	Wait 30s and retry; check docker compose logs mongodb
Error: Cannot find module	Image pull incomplete	docker compose pull && docker compose up -d
Blank page after login	JWT secrets are placeholder values	Set real 64-char hex values, restart
Ollama endpoint missing in UI	librechat.yaml not mounted	Confirm override file volume mount is uncommented

---

Step 5: Create Your Account

Go to http://localhost:3080/register. Fill in a name, email, and password. This creates a local account stored in MongoDB — no OAuth, no email verification required in default config.

Once your account is created, disable open registration:

# .env
ALLOW_REGISTRATION=false

Then restart:

docker compose up -d

New signups will be blocked. You can re-enable registration or invite specific users via the Admin Panel (available in v0.8.5+: click the gear icon in the sidebar → Users).

---

Step 6: Verify the Ollama Connection

In the chat interface, click the model selector (top center). You should see “Ollama” in the endpoint list. Select it and pick a model from the dropdown.

If no models appear despite fetch: true:

# Test that Ollama is running on your host
curl http://localhost:11434/api/tags

# Test that Docker can reach it
docker exec librechat-api-1 curl http://host.docker.internal:11434/api/tags

If the second command fails but the first succeeds, the extra_hosts fix from Step 3 is what you need.

---

Adding a Cloud API Alongside Ollama

You don’t have to choose. Add your OpenAI key to .env:

OPENAI_API_KEY=sk-proj-...

Restart, and the OpenAI endpoint appears in the model selector automatically — no librechat.yaml entry needed for built-in providers. You can now start a conversation with gpt-4o-mini for quick tasks, then switch the same thread to your local llama3.2:latest for anything private. Message history carries over on model switch.

The same pattern works for Anthropic (ANTHROPIC_API_KEY=sk-ant-...), Groq (GROQ_API_KEY=...), and others. LibreChat auto-detects built-in provider endpoints from .env key names.

---

Step 7: Enable Plugins

The Plugins endpoint is a separate system from custom endpoints. Switch to it from the endpoint selector to access tools like web search, image generation, and calculators attached to your conversation.

Google Search: Requires a Google Custom Search API key and a Search Engine ID. Add to .env:

GOOGLE_SEARCH_API_KEY=AIza...
GOOGLE_CSE_ID=your_cse_id_here

Restart, select the Plugins endpoint, click the wrench icon in the chat bar, and enable “Google Search.”

DALL-E image generation: Uses your OpenAI API key. When OPENAI_API_KEY is set, DALL-E-3 appears in the Plugins tool list automatically.

Wolfram Alpha (math, science calculations): Get a free Wolfram Alpha API appid and add:

WOLFRAM_APPID=your_appid

Each plugin is toggled per-conversation. The Plugins system routes tool calls through the active model, so model capability matters — gpt-4o handles multi-tool calls reliably; smaller local models are hit or miss below 14B parameters.

---

Step 8: Build a Custom Agent

Agents in LibreChat v0.8.6 are persistent, reusable assistants that carry a fixed system prompt and a curated tool set. They’re distinct from the Plugins endpoint and work with any configured model provider.

To create one:

1. Click Agents in the endpoint selector
2. Open the Agent Builder panel (right sidebar)
3. Set a name, system prompt, and model
4. Click Add Tools to attach capabilities: web search, code interpreter, file access, or any MCP server you’ve configured in librechat.yaml

Example system prompt for a code review agent:

You are a senior backend engineer doing code review. Focus on:
- Security issues: SQL injection, auth bypass, secrets in code
- Performance: O(n²) patterns, unnecessary DB queries, N+1 selects
- Missing error handling in I/O and external API calls

Point to specific line numbers. Be direct. Don't summarize what the code does.

Save the agent. It appears in the Agents dropdown and persists across sessions. Agents are per-user by default; admins can share them across accounts.

Note on local models for agents: Tool calling works best at 14B+. Qwen2.5 14B and Mistral 7B Instruct handle basic tool calls; smaller models frequently ignore tool invocations or hallucinate function signatures.

---

Optional: nginx Reverse Proxy + SSL

For access outside localhost — a home lab behind Tailscale, a VPS, or any remote deployment — put LibreChat behind nginx with Let’s Encrypt:

server {
    listen 443 ssl;
    server_name chat.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/chat.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 300s;
    }
}

The proxy_read_timeout 300s is critical. LibreChat uses server-sent events for streaming responses, and nginx’s default 60-second timeout kills long generations mid-sentence.

Update .env to match your domain:

DOMAIN_CLIENT=https://chat.yourdomain.com
DOMAIN_SERVER=https://chat.yourdomain.com

Restart after editing .env:

docker compose up -d

---

LibreChat vs. Alternatives

	LibreChat v0.8.6	Open WebUI	Jan.ai
Multi-provider	15+ providers natively	Ollama-first, OpenAI-compat	Ollama + OpenAI
Agents / assistants	Full Agent Builder (v0.8.6)	Basic presets	None
Plugin tools	Plugins endpoint (search, DALL-E, WA)	Tool use via model	None
Multi-user auth	Admin Panel, roles, groups (v0.8.5+)	Yes	Basic
RAG / file upload	RAG API via pgvector (built-in)	Built-in	None
Docker services	5 (api, mongo, meili, vectordb, rag)	1	Desktop app
Setup time	~20 min	~5 min	~3 min
Best for	Feature-rich team + multi-provider	Local-first simplicity	Solo offline use

If you want local chat running in five minutes, Ollama + Open WebUI is the faster path. If you need multiple API providers, team authentication, and a real agent framework, LibreChat is worth the overhead.

---

Common Pitfalls

.env variable names change between minor versions. If you’re upgrading from v0.7.x, diff your old .env against the current .env.example before restarting. Some variables were renamed or removed in the v0.8 series. The OPENAI_API_KEY name is stable; PROXY handling and some auth variables are not.

Port conflicts. LibreChat’s MongoDB runs on 27017 and Meilisearch on 7700. If you already run either service locally, Docker will throw a port bind error on docker compose up. Override conflicting ports in docker-compose.override.yml:

services:
  mongodb:
    ports:
      - "27018:27017"
  meilisearch:
    ports:
      - "7701:7700"

Agents and plugins not available in the model selector. Both appear as separate endpoint options (“Agents”, “Plugins”) alongside your configured providers. If they’re missing, check that docker compose logs api shows no startup errors — they can be disabled via librechat.yaml under interface:.

Tool calls failing with small local models. Tool/function calling is not uniformly supported across GGUF quantizations. If an agent ignores tool calls, switch to a model with explicit function-call support. The qwen2.5:14b and llama3.2:3b (specifically the 3B Instruct version) are reliable starting points.

---

When NOT to Use LibreChat

• Solo user who only needs local chat: Open WebUI gets you there in one Docker command with zero config files. The five-service LibreChat stack is overhead you don’t need.
• Running on a machine with under 2 GB RAM: The full LibreChat stack (MongoDB, Meilisearch, RAG API, vectordb, api) needs headroom. It works at 2 GB but barely.
• Wants native mobile app: LibreChat is browser-only. Jan.ai ships a proper cross-platform desktop app.
• Needs GPU-managed model downloads from the UI: Open WebUI can pull, delete, and manage Ollama models from the browser. LibreChat treats model management as Ollama’s problem.

For GPU-heavy workloads or cloud inference for larger models, RunPod gives you on-demand GPU instances at competitive per-hour rates without the hardware overhead.

For a broader feature comparison, see the LibreChat review and LibreChat vs Open WebUI vs Chatbot UI comparison.

---

FAQ

Does LibreChat work without any API keys? Yes, as long as you have Ollama running locally. Configure Ollama as a custom endpoint in librechat.yaml, and you have a fully functional chat interface with no cloud spend.

How do I update LibreChat to a new version?

docker compose pull
docker compose up -d

Check librechat.ai/changelog before upgrading — .env variable names sometimes change between minor versions.

Can multiple people use the same LibreChat instance? Yes. The Admin Panel (v0.8.5+, accessible via the sidebar gear icon) manages users, roles, and endpoint access per group. You can create custom roles with different provider access levels.

Why is the Plugins endpoint different from the Ollama custom endpoint? The Plugins endpoint routes through a tool-calling framework that injects function signatures into the prompt context. Custom endpoints (Ollama, OpenAI, Anthropic) are direct API passthrough. For tool use on custom endpoints, use the Agents system instead — it’s more capable and persists across sessions.

What’s the difference between LibreChat Agents and the Plugins endpoint? Plugins are single-session tools. Agents are persistent: they carry a system prompt, a tool set, and a selected model across sessions and can be shared with other users on the instance. The Agents system (significantly expanded in v0.8.6) is the direction LibreChat is moving; the Plugins endpoint is the older approach.

---

Sources

• LibreChat GitHub repository
• LibreChat Docker setup documentation
• LibreChat Ollama endpoint configuration
• LibreChat v0.8.6 changelog
• LibreChat Agents documentation
• LibreChat Google Search plugin setup
• LibreChat .env.example reference