librechat.ai/content/docs/configuration/librechat_yaml/index.mdx

---
title: Custom Config
icon: BookOpen
description: 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

<Steps>
  <Step>

### Locate or Create the File

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

```bash
touch librechat.yaml
```

You can also copy the [example config](/docs/configuration/librechat_yaml/example) as a starting point:

```bash
cp librechat.example.yaml librechat.yaml
```

<Callout type="info" title="Alternative File Path">

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

```bash filename=".env"
CONFIG_PATH="/alternative/path/to/librechat.yaml"
```

</Callout>

  </Step>
  <Step>

### Mount the Config File

<Tabs items={['Docker', 'Local']}>
  <Tabs.Tab>

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

**Copy the example override file:**

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

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

```yaml filename="docker-compose.override.yml"
services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
```

This uses the [docker-compose.override.yml](/docs/configuration/docker_override) pattern -- Docker Compose automatically merges it with the main `docker-compose.yml`, so your customizations survive updates.

  </Tabs.Tab>
  <Tabs.Tab>

Place `librechat.yaml` in the project root directory (the same directory as your `.env` file). No additional mounting is needed for local installations.

  </Tabs.Tab>
</Tabs>

  </Step>
  <Step>

### Restart LibreChat

<Tabs items={['Docker', 'Local']}>
  <Tabs.Tab>

```bash
docker compose down && docker compose up -d
```

  </Tabs.Tab>
  <Tabs.Tab>

Stop the running process (Ctrl+C) and restart:

```bash
npm run backend
```

  </Tabs.Tab>
</Tabs>

  </Step>
  <Step>

### 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:

```bash
docker compose logs api
```

  </Step>
</Steps>

## Example: Adding OpenRouter

This example walks through adding [OpenRouter](https://openrouter.ai/) as a custom endpoint -- one of the most popular configurations.

**1. Get an API key** from [openrouter.ai/keys](https://openrouter.ai/keys).

**2. Add the key to your `.env` file:**

```bash filename=".env"
OPENROUTER_KEY=sk-or-v1-your-key-here
```

<Callout type="warning" title="Environment Variable Name">

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

</Callout>

**3. Add the endpoint to `librechat.yaml`:**

```yaml filename="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](/docs/configuration/librechat_yaml/example).

## Reference

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

<Cards num={2}>
  <Cards.Card title="AI Endpoints" href="/docs/configuration/librechat_yaml/ai_endpoints" arrow>
    Compatible AI providers and example endpoint configurations
  </Cards.Card>
  <Cards.Card title="Object Structure" href="/docs/configuration/librechat_yaml/object_structure" arrow>
    Complete field reference for every librechat.yaml option
  </Cards.Card>
</Cards>

## Troubleshooting

### Configuration Validation

<Callout type="error" title="Configuration Validation">

LibreChat exits with an error (exit code 1) if `librechat.yaml` contains validation errors. This fail-fast behavior catches configuration issues early.

To validate your YAML syntax before restarting, use the [YAML Validator](/toolkit/yaml_checker) or [yamlchecker.com](https://yamlchecker.com/).

</Callout>

### Server Exits Immediately on Startup

If your server exits immediately after starting, this is likely a configuration validation error.

**To diagnose:**

1. Check server logs: `docker compose logs api`
2. Validate your YAML syntax with the [YAML Validator](/toolkit/yaml_checker)
3. Common errors: incorrect indentation, missing colons, unknown keys, invalid values

**Temporary workaround** (not recommended for production):

```bash filename=".env"
CONFIG_BYPASS_VALIDATION=true
```

<Callout type="warning" title="Warning">

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

</Callout>