# LibreChat + Luma Cloud

Add a Luma Cloud custom endpoint to your LibreChat installation.

API connection: Chat Completions. Instructions checked: 2026-09-28. Client capabilities and versions may vary; follow the verification steps below.

This is an API setup guide. SuperGPT desktop installation and sign-in are separate; use a customer API key for the client described here.

## Before you start

- Create a named key in Dashboard → API. Use API Wallet credit, or an eligible Builder subscription key.

- Copy an exact model ID from the catalog returned for this key. Replace MODEL_ID_FROM_CATALOG wherever it appears below.

- Use a separate named key for this app. Paste it only into the app's credential field; keep it out of chat prompts, screenshots, shared configuration and workflow exports.

- Permission to edit your LibreChat configuration and restart your installation. Keep a copy of the existing configuration before editing it.

## Setup

1. **Store the key separately**
   Set LUMA_CLOUD_API_KEY in the server's environment or private .env file. The YAML example reads that variable; the key itself stays out of librechat.yaml and source control.

2. **Merge the custom endpoint**
   Add the example under endpoints.custom in librechat.yaml, preserving its version and existing entries. Replace MODEL_ID_FROM_CATALOG. For a new configuration file, use the version from your installed release's example.

3. **Make the file available**
   Ensure LibreChat loads your librechat.yaml. With Docker Compose, merge its bind mount into the api service's volumes in docker-compose.override.yml: ./librechat.yaml maps to /app/librechat.yaml. Preserve existing volumes.

4. **Restart and choose Luma Cloud**
   Restart using your installation's normal procedure. Open a new conversation, select the Luma Cloud endpoint, then choose a model returned for your key.

5. **Send a first message**
   Ask “Reply with hello.” Start without files or tools so the result checks the text connection.

## Connection fields

- Server environment variable: LUMA_CLOUD_API_KEY

- baseURL: https://api.lumaos.cloud/v1

- models.fetch: true — load the authenticated model list

- models.default: MODEL_ID_FROM_CATALOG — fallback list if discovery fails

- titleConvo: false — no automatic title requests

## Add to librechat.yaml

```yaml
endpoints:
  custom:
    - name: "Luma Cloud"
      apiKey: "${LUMA_CLOUD_API_KEY}"
      baseURL: "https://api.lumaos.cloud/v1"
      models:
        default: ["MODEL_ID_FROM_CATALOG"]
        fetch: true
      titleConvo: false
      modelDisplayLabel: "Luma Cloud"
```

models.default is a fallback list, not permission to use an unavailable model. To enable automatic titles later, set titleConvo to true and titleModel to current_model; title generation makes additional requests.

## Private server environment

```dotenv
LUMA_CLOUD_API_KEY=YOUR_LUMA_CLOUD_API_KEY
```

Replace the placeholder in your private environment or secret manager. Do not commit this file. Make sure the api process or container actually receives the variable.

## Merge into docker-compose.override.yml

```yaml
services:
  api:
    volumes:
      - ./librechat.yaml:/app/librechat.yaml:ro
    environment:
      LUMA_CLOUD_API_KEY: ${LUMA_CLOUD_API_KEY}
```

This is an addition to an existing Compose installation, not a complete deployment file. Preserve its other services, environment and volumes. The variable must be supplied to Compose from a private source.

## For an installation where each user supplies a key

```yaml
apiKey: "user_provided"
```

Replace only the apiKey value inside the Luma Cloud endpoint. Keep its baseURL fixed to the Luma Cloud address. Each user then enters their own key through LibreChat.

## Verify

- Confirm the conversation uses Luma Cloud and receives a completed text reply.

- After the reply, open Dashboard → Usage. Check API Wallet for a wallet key, or subscription usage for a Builder subscription key.

- If Luma Cloud is missing, check the YAML file load or Docker mount. If authentication fails, check that the server received LUMA_CLOUD_API_KEY without printing the value.

## Limits

- The environment-key example is for your own installation. For a shared installation, set apiKey to user_provided instead, so LibreChat asks each user for their own key.

- File search, embeddings and hosted tools require separate compatible services. They are not configured by this chat endpoint.

## Troubleshooting

### 401 or an invalid-key message

Confirm that the saved credential contains a Luma Cloud API key, without surrounding quotes, spaces or a Bearer prefix. Check that this key is still active in Dashboard → API. A dashboard password or another provider's key will not work.

### Luma Cloud is missing from the endpoint selector

Check YAML indentation, the configuration version required by your installed LibreChat release, and whether the api service loads this file. In Compose, check the /app/librechat.yaml mount. Restart only after saving a valid configuration.

### Authentication works on the host but fails in LibreChat

Check whether LUMA_CLOUD_API_KEY is supplied to the api process or container. A variable set only in your terminal does not automatically reach an existing container. Recreate or restart through your normal installation procedure without printing the key.

### 404, or a fallback model cannot answer

baseURL must be https://api.lumaos.cloud/v1; leave directEndpoint unset. Keep the exact model ID in models.default and verify it is available to this key. Discovery and the fallback list are separate from permission to use the model.

### Chat succeeds, but titles or tools fail

Keep titleConvo false during setup. If you later enable it, select a title model that this key can use. Configure tools and retrieval separately and test each operation before using a shared workflow.

### 429, a balance warning or an interrupted run

Read the error and check the usage associated with this key. A wallet key uses API Wallet funds; a Builder subscription key uses its eligible subscription quota. Pause retries, wait for the indicated reset or retry time, and reduce parallel requests. After a timeout, check the existing result before running a costly job again.

## Official client documentation

- [LibreChat: custom endpoints setup](https://www.librechat.ai/docs/quick_start/custom_endpoints)

- [LibreChat: endpoint configuration reference](https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/custom_endpoint)