# Custom Config (https://www.librechat.ai/docs/configuration/librechat_yaml)

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

<Callout type="info" title="If you only remember one thing">

For Docker installs, editing `librechat.yaml` is not enough. The file must exist in the project root, be mounted into the API container, and LibreChat must be restarted before changes appear in the UI.

</Callout>

<Callout type="info" title="Prefer a UI? Use the Admin Panel">

The [**LibreChat Admin Panel**](/docs/features/admin_panel) manages this same configuration from a browser -- including per-role and per-group overrides that take effect at login without restarting LibreChat. It ships with the official Docker Compose stacks. Use `librechat.yaml` for file-driven or bootstrap setup, and the admin panel for ongoing management.

</Callout>

## 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/config"
    arrow
  >
    Complete field reference for every librechat.yaml option
  </Cards.Card>
</Cards>

## Troubleshooting

### Change Does Not Show in LibreChat

If you edited `librechat.yaml` and nothing changed in the UI:

1. Confirm the file is in the LibreChat project root unless you set `CONFIG_PATH`.
2. For Docker, confirm the file is mounted in `docker-compose.override.yml`.
3. Restart LibreChat with `docker compose down && docker compose up -d`.
4. Check the API logs with `docker compose logs api`.
5. Validate the file with the [YAML Validator](/toolkit/yaml_checker).

Custom endpoints such as OpenRouter only appear after all three pieces are correct: `.env` contains the key, `librechat.yaml` defines the endpoint, and Docker can read the mounted config file.

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