> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LibreChat | AI Gateway

> Route every LibreChat conversation through the Orq.ai AI Gateway. Add one librechat.yaml endpoint to reach the full model catalog with unified tracing.

## Overview

[LibreChat](https://www.librechat.ai/) is an open-source, self-hosted chat interface. Adding the **AI Gateway** as a custom endpoint routes every conversation through **Orq.ai**, exposing the full model catalog with unified tracing and cost tracking.

<Note>
  Custom endpoints exist only in [`librechat.yaml`](https://www.librechat.ai/docs/configuration/librechat_yaml); LibreChat has no UI for adding an OpenAI-compatible provider. This page covers model routing and tracing only.
</Note>

## Prerequisites

* [Docker](https://docs.docker.com/get-started/get-docker/) installed
* Active **Orq.ai** account
* [Orq.ai API key](/docs/ai-studio/organization/api-keys)

## Setup

<Steps>
  <Step title="Install LibreChat">
    Clone the repository and create the environment file. For other install methods, see the [LibreChat Docker guide](https://www.librechat.ai/docs/local/docker):

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    git clone https://github.com/danny-avila/LibreChat.git
    cd LibreChat
    cp .env.example .env
    ```
  </Step>

  <Step title="Add the API key to .env">
    Add the key to the LibreChat `.env` file:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    ORQ_API_KEY=<orq-api-key>
    ```

    Replace `<orq-api-key>` with the key from [Organization > API Keys](/docs/ai-studio/organization/api-keys).
  </Step>

  <Step title="Add the AI Gateway endpoint to librechat.yaml">
    Add a custom endpoint under a single top-level `endpoints` key:

    ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    endpoints:
      custom:
        - name: "orq"
          apiKey: "${ORQ_API_KEY}"
          baseURL: "https://api.orq.ai/v3/router"
          models:
            default: ["openai/gpt-4o", "anthropic/claude-sonnet-4-6"]
            fetch: true
          titleConvo: true
          titleModel: "openai/gpt-4o-mini"
          modelDisplayLabel: "orq"
    ```

    With `fetch: true`, the picker is populated live from the **AI Gateway**, so every enabled model appears automatically; `default` is only a fallback. Use provider-prefixed IDs (for example `openai/gpt-4o`) from [Workspace Settings → Models](https://my.orq.ai/settings/models).
  </Step>

  <Step title="Mount the config and restart">
    LibreChat reads `librechat.yaml` only when it is [mounted into the container](https://www.librechat.ai/docs/configuration/librechat_yaml). After mounting, recreate the containers so the new `.env` and config are loaded:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    docker compose down && docker compose up -d
    ```
  </Step>
</Steps>

<Note>
  **Apple Silicon:** the default MongoDB image requires AVX instructions that Apple Silicon does not expose under virtualization, so the `mongodb` container crash-loops. Pin `mongo:4.4.18` in `docker-compose.override.yml` to fix it.
</Note>

## Configuration Reference

| Field            | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| `name`           | Endpoint label shown in the model picker.                                         |
| `apiKey`         | References the `.env` variable holding the **Orq.ai** key, e.g. `${ORQ_API_KEY}`. |
| `baseURL`        | Set to `https://api.orq.ai/v3/router` for all **AI Gateway** models.              |
| `models.fetch`   | When `true`, populates the picker live from the catalog. Recommended.             |
| `models.default` | Fallback list of provider-prefixed IDs.                                           |
| `titleConvo`     | When `true`, fires a second call to `titleModel` to name each conversation.       |
| `titleModel`     | Model used to generate conversation titles.                                       |

## Troubleshooting

<AccordionGroup>
  <Accordion title="The orq endpoint or its models do not appear">
    The custom endpoint did not load. Confirm `ORQ_API_KEY` is set in `.env`, that there is exactly one top-level `endpoints` key in `librechat.yaml`, and that the file is mounted into the container. See the [LibreChat config docs](https://www.librechat.ai/docs/configuration/librechat_yaml).
  </Accordion>

  <Accordion title="Only a few models appear in the picker">
    The endpoint is running with `fetch: false`. Set `fetch: true` to populate the picker from the **AI Gateway** catalog, and confirm `baseURL` is `https://api.orq.ai/v3/router`.
  </Accordion>

  <Accordion title="Requests do not appear in Orq.ai Traces">
    Confirm `apiKey` resolves to a valid **Orq.ai** [API key](/docs/ai-studio/organization/api-keys) and `baseURL` is `https://api.orq.ai/v3/router`. Requests sent to another endpoint will not appear in **Traces**.
  </Accordion>

  <Accordion title="Two requests traced per message">
    `titleConvo: true` fires a second call to `titleModel` to name the conversation. This is expected. Set `titleConvo: false` to disable it, or point `titleModel` at a cheaper model.
  </Accordion>
</AccordionGroup>

## Verification

Select the **orq** endpoint in the model picker, choose a model, and send a message. The response appears in the chat, and the request appears in [**Orq.ai** Traces](/docs/ai-studio/observability/traces) with the selected model identifier.