The Complete LibreChat YAML Configuration Guide

The librechat.yaml file is your control center for a self-hosted LibreChat deployment. It defines endpoints (which AI models you offer), user interface settings, caching behavior, and registration rules. Without it, LibreChat cannot start. If you are running LibreChat in Docker or on your own server, you need to understand where this file lives and how to configure it correctly.

Most LibreChat setup problems trace back to YAML configuration: file location mistakes, missing environment variables, indentation errors, and Redis cache stale data. This guide walks you through each section, shows you a working minimal config, and highlights the pitfalls that cost hours of debugging.

What Is librechat.yaml and Where Does It Live?

The librechat.yaml file is LibreChat's main configuration file. It tells LibreChat which AI endpoints to use, what models to offer, how to customize the user interface, and how to manage users and caching. Think of it as a blueprint: without it, LibreChat is a blank canvas. With it, you control every detail of the user experience.

Location depends on your deployment:

Docker: Mount it at /app/librechat.yaml inside the container. You must define this in your docker-compose.yml using a volume binding:

volumes:
  -./librechat.yaml:/app/librechat.yaml

If you do not mount the file, Docker will not see it, and LibreChat will fail to start with an unclear error message.

Local installation (Node.js): Place the file in your project root, or in the .librechat_config directory in your home folder. LibreChat checks multiple locations in order.

The three-file pattern: Most teams use three files together:

1. .env -- secrets and API keys (never commit to version control)
2. librechat.yaml -- configuration (can be version-controlled)
3. docker-compose.override.yml -- optional overrides for local development

Missing or misaligned files are the number-one source of "it works on my machine but not in Docker" frustration. Always verify the mount path first.

The Four Core Sections Explained

Every librechat.yaml file contains four main sections at the top level: version, cache, endpoints, and interface. Understanding the purpose of each prevents misconfiguration.

Version: Specifies which librechat.yaml schema version you are using. Currently, most deployments use version 1.0 or 1.1. Always start with:

version: 1.1

Cache: Controls LibreChat's in-memory and Redis caching for conversations. If your file has no cache section, LibreChat uses defaults (disabled). For production or team deployments, you will typically configure Redis here.

Endpoints: Defines the AI providers and models your users can access. OpenAI, Anthropic, OpenRouter, Ollama, Azure OpenAI--all go here. This is where the bulk of your config lives.

Interface: Controls the UI, login requirements, registration rules, and token usage display. Team-oriented settings like user caps and context tracking live here.

If any of these sections is malformed, LibreChat will not start or will silently ignore your settings. The error messages are often vague. This is why a working example matters more than reference docs.

Setting Up Version and Cache Configuration

The version field is straightforward. Set it once, rarely change it.

Cache is where confusion often starts. LibreChat supports two cache backends:

In-memory (default): Stores cached data in server RAM. Fast, simple, and lossy--if you restart the container, the cache is gone. Suitable for single-server deployments or development.

Redis: Persists cache across restarts and scales across multiple server instances. Requires a separate Redis container or service. Production teams should use Redis.

Redis caching has a critical gotcha: changing your librechat.yaml and restarting LibreChat is not enough. The old config values are still in the Redis cache. You must either:

1. Clear the Redis cache manually: redis-cli FLUSHDB
2. Set a cache TTL (time to live) so stale data expires
3. Disable caching for development: cache: false

This accounts for 3+ bug reports on GitHub where developers swear they updated the config but nothing changed. The server restarted, but Redis remembered the old data.

If you are using Docker Compose, add both LibreChat and Redis:

services:
  librechat:
    image: ghcr.io/librechat-ai/librechat:latest
    environment:
      - REDIS_URI=redis://redis:6379
    volumes:
      -./librechat.yaml:/app/librechat.yaml

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Then in your librechat.yaml:

version: 1.1
cache:
  redis: true

Configuring Custom Endpoints (OpenRouter, Ollama, Claude-Compatible)

The endpoints section is where you tell LibreChat which AI services to use. Each endpoint is a provider (OpenAI, Anthropic, a third-party like OpenRouter, or a local Ollama instance). Each endpoint can offer multiple models.

Endpoint structure:

endpoints:
  openAI:
    apiKey: ${OPENAI_API_KEY}
    baseURL: (your OpenAI API endpoint)
    models:
      - gpt-4-turbo
      - gpt-4
      - gpt-3.5-turbo

The format is consistent across providers, but specific fields vary.

OpenRouter (aggregates many models):

endpoints:
  openRouter:
    apiKey: ${OPENROUTER_API_KEY}
    baseURL: (your OpenRouter API endpoint)
    models:
      - openai/gpt-4-turbo
      - claude-3-opus:beta
      - meta-llama/llama-2-70b-chat

OpenRouter is popular because it offers access to dozens of models--OpenAI, Anthropic, LLaMA, Mistral--through one API key and consistent pricing. If your team wants to avoid vendor lock-in, this is a smart choice.

Ollama (local models on your own hardware):

endpoints:
  ollama:
    baseURL: (your local Ollama endpoint)
    models:
      - fetch: true

Setting fetch: true tells LibreChat to pull the list of available models from Ollama automatically. No need to manually list every model. If you prefer explicit control, list them:

    models:
      - llama2
      - mistral
      - neural-chat

Anthropic-compatible (includes Azure, Replicate, and other Claude wrappers):

endpoints:
  anthropic:
    apiKey: ${ANTHROPIC_API_KEY}
    baseURL: (your Anthropic API endpoint)
    models:
      - claude-3-opus-20240229
      - claude-3-sonnet-20240229

Key fields on every endpoint:

• apiKey: Your authentication token. Use ${VAR_NAME} to reference environment variables. If you omit the ${} syntax, LibreChat treats it as a literal string, and authentication will fail.
• baseURL: The API endpoint. Different from apiKey--this is the server address, not the credential.
• models: Array of model identifiers. These must exactly match the provider's model names or they will not work.
• fetch (optional): If true, LibreChat queries the provider for available models at startup. Saves manual maintenance but adds startup time.
• title (optional): Custom name to show in the UI. Overrides the default provider name.

Environment variable resolution: Not all fields support ${VAR_NAME} syntax. Safe to use in:

• apiKey
• baseURL (sometimes)
• password fields

Unsafe in:

• model names
• boolean flags
• numeric values

If an env var does not resolve (stays as ${OPENAI_API_KEY} in logs), either the variable is not set in your .env file, or you are using it in a field that does not support substitution. Check your .env file, reload the container, and check the logs.

Customizing Interface Settings and Registration Limits

The interface section controls the user-facing aspects of LibreChat: branding, registration, token usage tracking, and conversation limits.

Custom welcome message:

interface:
  displayTitle: "Our Team's AI Assistant"
  displayWelcomeMessage: "Welcome to our internal AI chat platform. Please read our usage policy."

These appear on the login and home pages. Use them to set expectations about appropriate use or to rebrand LibreChat as your own product.

Registration limits (team deployments):

interface:
  registration:
    socialLogins: ["github", "google"]
    maxAttempts: 5
    timeWindow: 15

These are powerful for team deployments. If you want only GitHub employees to access LibreChat, enable GitHub OAuth and set allowRegistration: false to disable sign-ups.

Token usage tracking (show costs to users):

interface:
  showTokenUsage: true
  tokenUpdatesEnabled: true

When enabled, users see token counts and estimated costs for each conversation. Useful for controlling runaway spending or educating teams about model efficiency.

Context window limits (per-conversation):

interface:
  tokenCounterEnabled: true
  maxContextTokens: 8000

This prevents users from loading years of chat history into a single conversation, which would blow through your budget. Set it per-model if certain endpoints have smaller context windows.

A Minimal Complete Config for Your Team

Here is a working minimal config suitable for a team of 2-5 people using OpenRouter and local Ollama:

version: 1.1

cache:
  redis: false

endpoints:
  openRouter:
    apiKey: ${OPENROUTER_API_KEY}
    baseURL: (your OpenRouter endpoint)
    models:
      - openai/gpt-4-turbo
      - claude-3-opus:beta
      - meta-llama/llama-2-70b-chat
    title: "OpenRouter (Multi-Model)"

  ollama:
    baseURL: (your Ollama service endpoint)
    models:
      - fetch: true
    title: "Local Models (Ollama)"

interface:
  displayTitle: "Acme Corp AI Assistant"
  displayWelcomeMessage: "Welcome. Please do not share confidential customer data."
  showTokenUsage: true
  tokenCounterEnabled: true
  maxContextTokens: 8000
  registration:
    allowRegistration: true

What this config does:

• Offers two endpoint groups: one cloud-based (OpenRouter) with three models, one local (Ollama) auto-fetching available models
• Disables Redis caching (suitable for single-server test deployments)
• Shows token usage to users
• Limits conversations to 8,000 tokens (prevents budget overruns)
• Allows self-registration (remove this or set to false for team-only access)

Deploy it with docker-compose.yml:

version: '3.8'
services:
  librechat:
    image: ghcr.io/librechat-ai/librechat:latest
    ports:
      - "3080:3080"
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
    volumes:
      -./librechat.yaml:/app/librechat.yaml
      -./data:/data
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

volumes:
  ollama_data:

Your.env file:

OPENROUTER_API_KEY=sk-or-xxxxx

Run docker-compose up, visit your LibreChat instance at the configured port, and you have a working instance with two provider options. Users can pick which models to use.

Seven Common Mistakes and How to Fix Them

These mistakes appear in GitHub issues and forums weekly. Knowing them saves hours.

1. Missing librechat.yaml in Docker mount

Symptom: Container starts but immediately exits, or LibreChat says "no config file found."

Fix: Verify the volume mount in docker-compose.yml:

volumes:
  -./librechat.yaml:/app/librechat.yaml

Make sure ./librechat.yaml exists in your project directory, not in a subdirectory.

2. Indentation errors in YAML

Symptom: "YAML parsing error" in logs, or settings are silently ignored.

Fix: YAML is indentation-sensitive. Spaces, not tabs. Verify with a YAML linter: https://www.yamllint.com. Copy the config into the linter, and it will highlight bad indentation.

3. Environment variables not resolved

Symptom: Logs show ${OPENAI_API_KEY} instead of your actual key, and authentication fails.

Fix: Check two things:

1. Variable is set in.env: OPENAI_API_KEY=sk-... 2..env is mounted in docker-compose.yml:

env_file:
  -.env

4. Redis cache retains old config

Symptom: You updated librechat.yaml and restarted, but the old settings are still active.

Fix: Clear Redis after restarting:

docker-compose exec redis redis-cli FLUSHDB

Or disable caching temporarily:

cache: false

5. Missing required fields in endpoint definition

Symptom: Endpoint does not appear in the UI, or mysterious errors in logs.

Fix: Every endpoint needs:

• apiKey (if authentication required)
• baseURL
• At least one model in the models array

If any is missing, the entire endpoint is skipped.

6. Model name mismatch

Symptom: Model is listed in the config but returns an error when a user selects it.

Fix: Model names must exactly match the provider's identifier. For OpenAI, it is gpt-4-turbo, not GPT-4 Turbo or gpt4turbo. Check the provider's API docs or use their model listing API to verify the correct identifiers.

7. Port conflicts in Docker

Symptom: "Address already in use" when starting containers.

Fix: Check which process is using the port:

lsof -i :3080

Kill the existing process or map LibreChat to a different port in docker-compose.yml:

ports:
  - "3081:3080"

From Self-Hosted Config to Managed Hosting

Managing librechat.yaml yourself works for small teams. You own every detail, and you avoid recurring costs. But it has hidden costs: your time.

You are now responsible for:

• Keeping the config in sync across dev and production
• Monitoring Redis and handling cache issues
• Upgrading LibreChat when new versions break your config
• Scaling the server when usage grows
• Securing API keys and database backups

For a 10-50 person team, these tasks can add 5-10 hours per month to your operations workload. If your team is lean, that is painful.

This is where managed hosting makes sense. Opsily offers managed LibreChat hosting where we handle the config, updates, and scaling. You define your endpoints and interface settings, and we ensure they work. Your YAML stays simple, and we handle the operational burden.

If your deployment grows beyond a single team or you need audit trails and compliance features, Opsily's hosted LibreChat option handles multi-tenant deployments, SSO integration, and detailed usage tracking.

For Docker deployments running on your own infrastructure, our Docker hosting guide walks through the same config patterns at scale.

Frequently Asked Questions

Where do I find an example librechat.yaml?

The LibreChat GitHub repository includes example configs at docs/examples/librechat.example.yaml. It is comprehensive but often does not work out of the box because required environment variables are not set. Use the minimal config in this guide as a starting point, then add your own endpoints.

Can I use environment variables in model names?

No. Model names must be literal strings matching the provider's identifier. You can use ${VAR} syntax for API keys and URLs, but not for model names, boolean flags, or numeric values.

What does the version field do?

It specifies which librechat.yaml schema version you are using. LibreChat may support multiple versions for backward compatibility. Always set version: 1.1 or the latest available in your LibreChat release. Mismatched versions can cause config parsing errors.

How do I list available models from my providers?

Consult each provider's API documentation. OpenAI, Anthropic, OpenRouter, and Ollama all provide endpoints to list their available models. Check the provider's API reference for the correct method.

Can I host librechat.yaml in a database instead of a file?

Not out of the box. LibreChat expects a YAML file. Some teams work around this by generating the file at startup from a database or config management system, but it requires custom scripting. For most teams, file-based config in version control is simpler.

Do I need Redis for production?

No, but you should. Redis enables caching across container restarts and scales to multiple LibreChat instances. In-memory caching works for single-server deployments with low traffic, but adds operational risk. For any team deployment, Redis is worth the extra 30 seconds of setup.

How do I disable registration to run LibreChat for my team only?

Set allowRegistration: false in the interface section, and configure OAuth (GitHub, Google) or LDAP. Users must be invited or authenticated via your identity provider. Without this, anyone who finds your URL can sign up.

The Bottom Line

LibreChat.yaml is not complicated, but it rewards carefulness. The file has four main sections (version, cache, endpoints, interface), each with specific purpose. Endpoints define the AI models your users access; interface controls branding and registration. The biggest mistakes are file mount issues, indentation errors, and stale Redis cache data--all easy to prevent if you know what to look for.

Start with the minimal config provided in this guide, test it locally, then scale to your team. If you are running this yourself, plan for the operational overhead: config drift, version upgrades, API key rotation. If that sounds like overhead you would rather skip, Opsily's hosted LibreChat option handles the config and operations for you.