Custom Config

Create, mount, and configure the librechat.yaml file for custom AI endpoints and advanced LibreChat settings

What is librechat.yaml?

The librechat.yaml file is LibreChat's main configuration file for custom AI endpoints, model settings, interface options, and advanced features like MCP servers and agents. It is optional -- LibreChat works with sensible defaults if the file does not exist.

Follow the steps below to create the file, mount it for your deployment type, and verify it works.

Setup

Locate or Create the File

Create a new librechat.yaml in your project root (the same directory as your .env file):

touch librechat.yaml

You can also copy the example config as a starting point:

cp librechat.example.yaml librechat.yaml

Alternative File Path

You can set a custom file path using the CONFIG_PATH environment variable:

CONFIG_PATH="/alternative/path/to/librechat.yaml"

Mount the Config File

Docker needs a volume mount to access your librechat.yaml file inside the container.

Copy the example override file:

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

Edit docker-compose.override.yml and ensure the librechat.yaml volume mount is uncommented:

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

This uses the docker-compose.override.yml pattern -- Docker Compose automatically merges it with the main docker-compose.yml, so your customizations survive updates.

Restart LibreChat

docker compose down && docker compose up -d

Verify It Works

Open LibreChat in your browser. If your configuration includes custom endpoints, you should see them in the model selector dropdown.

If the server fails to start, check the logs for validation errors:

docker compose logs api

Example: Adding OpenRouter

This example walks through adding OpenRouter as a custom endpoint -- one of the most popular configurations.

1. Get an API key from openrouter.ai/keys.

2. Add the key to your .env file:

OPENROUTER_KEY=sk-or-v1-your-key-here

Environment Variable Name

Use OPENROUTER_KEY, not OPENROUTER_API_KEY. Using OPENROUTER_API_KEY will override the OpenAI endpoint to use OpenRouter as well.

3. Add the endpoint to librechat.yaml:

version: 1.3.5
cache: true
endpoints:
  custom:
    - name: "OpenRouter"
      apiKey: "${OPENROUTER_KEY}"
      baseURL: "https://openrouter.ai/api/v1"
      models:
        default: ["meta-llama/llama-3-70b-instruct"]
        fetch: true
      titleConvo: true
      titleModel: "meta-llama/llama-3-70b-instruct"
      dropParams: ["stop"]
      modelDisplayLabel: "OpenRouter"

4. Restart LibreChat (see restart commands above) and select OpenRouter from the model selector.

For the full annotated config file with more endpoint examples, see the example configuration.

Reference

For detailed field-level documentation, see the reference pages below.

AI Endpoints

Compatible AI providers and example endpoint configurations

→

Object Structure

Complete field reference for every librechat.yaml option

→

Check server logs: docker compose logs api
Validate your YAML syntax with the YAML Validator
Common errors: incorrect indentation, missing colons, unknown keys, invalid values

Temporary workaround (not recommended for production):

CONFIG_BYPASS_VALIDATION=true

Warning

CONFIG_BYPASS_VALIDATION=true causes the server to skip validation and use default configuration. Always fix the validation errors instead.