DEV Community

Jovan Chan
Jovan Chan

Posted on • Originally published at aifoss.dev

LibreChat Setup Guide 2026: Plugins, Agents, and Ollama

#librechat #ollama #selfhosted #docker

This article was originally published on aifoss.dev

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

MEILI_MASTER_KEY=another_random_secret
Enter fullscreen mode Exit fullscreen mode

Registration control:

# Set to false once you've created your account
ALLOW_REGISTRATION=true
Enter fullscreen mode Exit fullscreen mode

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

OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Step 4: Start LibreChat 

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Then restart:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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-...
Enter fullscreen mode Exit fullscreen mode

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](https:

Top comments (0)