LibreChat + Luma Cloud

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.

Get an API key and a model ID →

Set up LibreChat

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.

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

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"

LUMA_CLOUD_API_KEY=YOUR_LUMA_CLOUD_API_KEY

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

apiKey: "user_provided"

Check the connection

1. Confirm the conversation uses Luma Cloud and receives a completed text reply.
2. After the reply, open Dashboard → Usage. Check API Wallet for a wallet key, or subscription usage for a Builder subscription key.
3. 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.

For errors or a request that stops, see troubleshooting. A visible model list alone does not confirm that a chat or editing task can complete.

What to expect

• 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 LibreChat