# Luma Cloud

> Customer setup and public API documentation.

Base URL: https://api.lumaos.cloud/v1
Choose a model from authenticated GET https://api.lumaos.cloud/v1/models with the user's own key. Never request the key in a conversation or send it to a documentation page.

## Start here

- [Quickstart](https://lumaos.cloud/docs/quickstart): Create a key and complete one request.
- [Integrations](https://lumaos.cloud/docs/installations): Choose your IDE, agent or chat app.
- [API](https://lumaos.cloud/docs/api): Authentication, Chat Completions and Responses.
- [Models](https://lumaos.cloud/docs/models): Model IDs, reasoning effort, limits and prices.
- [SDKs](https://lumaos.cloud/docs/sdks): Python, JavaScript and HTTP examples.
- [Usage](https://lumaos.cloud/docs/usage): Subscription quota and API Wallet usage.
- [Billing](https://lumaos.cloud/docs/billing): Plans, Wallet funding and additional quota.
- [Troubleshooting](https://lumaos.cloud/docs/errors): Error codes and safe recovery.
- [SuperGPT](https://lumaos.cloud/docs/installations/supercodex): Desktop setup and updates.
- [Agent setup](https://lumaos.cloud/docs/agents): A scoped setup prompt for an assistant.
- [Support](https://lumaos.cloud/docs/support): What to include in a support request.

## Client instructions

- [Continue · VS Code & JetBrains](https://lumaos.cloud/docs/installations/continue/llms.txt): Add Luma Cloud to Continue while keeping your other models and editor settings.
- [Cline](https://lumaos.cloud/docs/installations/cline/llms.txt): Connect the Cline extension with its OpenAI Compatible provider.
- [Kilo Code](https://lumaos.cloud/docs/installations/kilo-code/llms.txt): Create a named Luma Cloud provider and select models from your API catalog.
- [Roo Code](https://lumaos.cloud/docs/installations/roo-code/llms.txt): Use the OpenAI Compatible provider with a model that supports native tool calling.
- [VS Code · Chat & Copilot](https://lumaos.cloud/docs/installations/vscode/llms.txt): Add Luma Cloud with VS Code's Custom Endpoint model provider.
- [JetBrains AI Assistant](https://lumaos.cloud/docs/installations/jetbrains/llms.txt): Use Luma Cloud in AI Assistant across supported IntelliJ-based IDEs.
- [Zed](https://lumaos.cloud/docs/installations/zed/llms.txt): Add Luma Cloud as a separate provider for Zed's own AI features.
- [Cursor](https://lumaos.cloud/docs/installations/cursor/llms.txt): A conditional chat connection using Cursor's OpenAI base URL override.
- [Windsurf / Devin Desktop](https://lumaos.cloud/docs/installations/windsurf/llms.txt): Use a separately configured OpenCode agent through ACP where your editor plan supports it.
- [OpenCode](https://lumaos.cloud/docs/installations/opencode/llms.txt): Add Luma Cloud alongside your existing providers in OpenCode's classic configuration.
- [OpenCode V2](https://lumaos.cloud/docs/installations/opencode-v2/llms.txt): Use the V2 provider format without replacing your current OpenCode setup.
- [OpenClaw](https://lumaos.cloud/docs/installations/openclaw/llms.txt): Add a custom Luma Cloud provider and select it for one agent session.
- [Aider](https://lumaos.cloud/docs/installations/aider/llms.txt): Connect Aider for a single terminal run using its OpenAI-compatible provider.
- [Codex CLI](https://lumaos.cloud/docs/installations/codex-cli/llms.txt): Use Luma's Responses API for one CLI session while preserving your normal OpenAI configuration.
- [Claude Code](https://lumaos.cloud/docs/installations/claude-code/llms.txt): Direct connection needs Anthropic Messages compatibility, which is not a documented Luma API interface.
- [Gemini CLI](https://lumaos.cloud/docs/installations/gemini-cli/llms.txt): Gemini CLI's documented connection uses Google services rather than a generic OpenAI-compatible provider.
- [Open WebUI](https://lumaos.cloud/docs/installations/open-webui/llms.txt): Chat with Luma Cloud through an OpenAI-compatible connection.
- [AnythingLLM](https://lumaos.cloud/docs/installations/anythingllm/llms.txt): Use Luma Cloud as the language model for your workspace.
- [LibreChat](https://lumaos.cloud/docs/installations/librechat/llms.txt): Add a Luma Cloud custom endpoint to your LibreChat installation.
- [Cherry Studio](https://lumaos.cloud/docs/installations/cherry-studio/llms.txt): Keep Luma Cloud in its own provider entry and choose its models in chat.
- [n8n](https://lumaos.cloud/docs/installations/n8n/llms.txt): Add Luma Cloud text generation to a workflow with an OpenAI Chat Model node.
- [Dify](https://lumaos.cloud/docs/installations/dify/llms.txt): Configure a Luma Cloud chat model for a Dify app or workflow.
- [Flowise](https://lumaos.cloud/docs/installations/flowise/llms.txt): Use a custom OpenAI-compatible chat model in a Flowise Chatflow.
- [Any OpenAI-compatible client](https://lumaos.cloud/docs/installations/openai-compatible/llms.txt): Connect another editor, agent or app that accepts a custom OpenAI API URL and key.

## Full setup reference

- [Combined quickstart and client guides](https://lumaos.cloud/llms-full.txt)

Each client guide includes a check date, official sources, limitations and verification steps. Documentation review is not a completed test in the user's app. Preserve existing configuration and ask before billable verification.

---

# Luma Cloud API quickstart

1. Open /app/api. API Wallet is independent of your subscription. Add funds when available, create a named Wallet key and save it when shown once. Builder also offers separate keys using subscription quota.
2. Keep the key in local secure storage or LUMA_CLOUD_API_KEY; never send it in a chat or commit it.
3. Set Base URL to https://api.lumaos.cloud/v1. Choose OpenAI Compatible and Chat Completions, or Responses if required by your client.
4. Query GET https://api.lumaos.cloud/v1/models with the same key. Use an exact returned id for LUMA_CLOUD_MODEL; do not infer availability from a label.
5. Make one short request; actual inference uses quota or funds. Check output and API usage before enabling parallel tasks.

## Environment (macOS / Linux)

```sh
# macOS / Linux: enter the key when prompted, not in the command itself.
read -r -s LUMA_CLOUD_API_KEY
export LUMA_CLOUD_API_KEY
export LUMA_CLOUD_BASE_URL="https://api.lumaos.cloud/v1"
# Replace the value below with an ID returned for your key.
export LUMA_CLOUD_MODEL="MODEL_ID_FROM_CATALOG"
```

## Windows PowerShell 7

Enter the key privately, then choose a returned model ID when prompted. The request uses funds or quota.

```powershell
$env:LUMA_CLOUD_API_KEY = Read-Host "Luma Cloud API key" -MaskInput
$env:LUMA_CLOUD_BASE_URL = "https://api.lumaos.cloud/v1"
$env:LUMA_CLOUD_MODEL = "MODEL_ID_FROM_CATALOG"

$headers = @{ Authorization = "Bearer $env:LUMA_CLOUD_API_KEY" }
$models = Invoke-RestMethod "$env:LUMA_CLOUD_BASE_URL/models" -Headers $headers
$models.data | Select-Object id

$env:LUMA_CLOUD_MODEL = Read-Host "Model ID from the list above"
$body = @{
  model = $env:LUMA_CLOUD_MODEL
  messages = @(@{ role = "user"; content = "Reply with hello." })
  stream = $false
} | ConvertTo-Json -Depth 5
$result = Invoke-RestMethod "$env:LUMA_CLOUD_BASE_URL/chat/completions" -Method Post -Headers $headers -ContentType "application/json" -Body $body
$result.choices[0].message.content
```

## Models (macOS / Linux)

```sh
curl --fail-with-body "https://api.lumaos.cloud/v1/models" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY"
```

## Chat Completions

```sh
curl --fail-with-body -N "https://api.lumaos.cloud/v1/chat/completions" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "messages": [{"role": "user", "content": "Reply with hello."}],
  "stream": true
}
JSON
```

## Responses

```sh
curl --fail-with-body -N "https://api.lumaos.cloud/v1/responses" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "input": "Reply with hello.",
  "stream": true
}
JSON
```

A client model list is not an end-to-end verification. Test one chat, then any file/tool features you need in a disposable project. File editing is performed by the client. No direct Anthropic Messages or Gemini API endpoint is offered in these guides. Do not assume support for embeddings, image/audio generation, video, realtime audio, hosted assistants or file storage from OpenAI compatibility.

## Errors

401: check the key and Bearer header. 402: check the correct Wallet balance or subscription quota. 403/404: check the exact model id, permission and URL. 429: follow Retry-After, reduce simultaneous work, do not retry in a tight loop. 5xx/timeout: retry carefully after a delay; do not blindly repeat tool side effects. Save x-request-id or error.request_id for support. Never send the key to support.

See /docs/errors, /docs/models, /docs/billing and /docs/installations for details.


# Continue · VS Code & JetBrains + Luma Cloud

Add Luma Cloud to Continue while keeping your other models and editor settings.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Install Continue in VS Code or your supported JetBrains IDE.

## Setup

1. **Open the Continue extension**
   In VS Code, open Continue from the sidebar. In a JetBrains IDE, open its Continue tool window. Use Continue's configuration dropdown and the gear next to Local Config; this is separate from the editor's own AI settings.

2. **Edit the local model list**
   The file is ~/.continue/config.yaml on macOS/Linux and %USERPROFILE%\.continue\config.yaml on Windows. Back it up, then add the model under the existing models list. Do not create a second models key or remove the current name, version, schema, and other model entries.

3. **Save the key locally**
   Put LUMA_CLOUD_API_KEY=your-key in ~/.continue/.env, or %USERPROFILE%\.continue\.env on Windows. Keep this file out of Git. Restart the IDE after changing secrets; a shell export alone does not supply secrets to the extension.

4. **Save and select the model**
   Replace MODEL_ID_FROM_CATALOG with the exact ID. Save the YAML; Continue reloads model configuration. After adding the secret, restart the IDE, select Local Config, then choose Luma Cloud in Continue's model picker. Begin in Chat mode.

## Add this entry to models in config.yaml

```yaml
models:
  - name: Luma Cloud
    provider: openai
    model: MODEL_ID_FROM_CATALOG
    apiBase: https://api.lumaos.cloud/v1
    apiKey: ${{ secrets.LUMA_CLOUD_API_KEY }}
    useResponsesApi: false
    roles:
      - chat
```

This selects Chat Completions explicitly. Do not enable useLegacyCompletionsEndpoint. Add edit/apply roles or tool_use only after checking your chosen model's capabilities.

## New config.yaml only — when you have no existing configuration

```yaml
name: Luma Cloud
version: 1.0.0
schema: v1
models:
  - name: Luma Cloud
    provider: openai
    model: MODEL_ID_FROM_CATALOG
    apiBase: https://api.lumaos.cloud/v1
    apiKey: ${{ secrets.LUMA_CLOUD_API_KEY }}
    useResponsesApi: false
    roles:
      - chat
```

Replace the model placeholder. For an existing file, use the smaller model entry above instead of replacing your configuration.

## Secret file — ~/.continue/.env

```dotenv
LUMA_CLOUD_API_KEY=YOUR_LUMA_CLOUD_API_KEY
```

On Windows use %USERPROFILE%\.continue\.env. Replace the placeholder inside the local file, not in a terminal command. Do not publish, commit, or screenshot the populated file.

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

## Limits

- Chat configuration does not configure autocomplete, embeddings, or reranking. Those features need their own supported models.

- Agent mode needs a model with tool calling; do not force capabilities merely to make it appear.

## Troubleshooting

### The model does not appear

Select Local Config rather than a different cloud configuration. Check YAML indentation and duplicate models keys. Save the file, inspect Continue's configuration error, and reopen the extension.

### The key is empty even after a shell export

Continue's IDE extensions do not read your terminal exports. Put LUMA_CLOUD_API_KEY in the global .continue/.env file and restart the IDE. A workspace .env value can override the global value, so check for an older key there.

### Chat works but Agent or autocomplete does not

This example only enables the chat role. Agent mode needs supported tool use and appropriate model roles; autocomplete requires a model configured specifically for it. Do not enable capabilities to hide an unsupported-model error.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### Model not found or access denied

Copy the exact model ID available to this key from the authenticated catalog. MODEL_ID_FROM_CATALOG is a placeholder, not a model name. Do not substitute a display label or copy an ID from another provider.

## Official client documentation

- [Continue: OpenAI-compatible configuration](https://docs.continue.dev/customize/model-providers/top-level/openai)

- [Continue: local secrets](https://docs.continue.dev/faqs)

- [Continue: model roles and capabilities](https://docs.continue.dev/reference)

---

# Cline + Luma Cloud

Connect the Cline extension with its OpenAI Compatible provider.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Install Cline in a supported editor.

## Setup

1. **Open Cline's own settings**
   Open the Cline sidebar/tool window, then its gear icon. Find API Provider and select OpenAI Compatible. Changing VS Code Chat, Cursor Models, or JetBrains AI Assistant settings does not configure Cline.

2. **Enter URL and key**
   Set Base URL to https://api.lumaos.cloud/v1. Paste the Luma Cloud key into Cline's API Key field on macOS, Windows, or Linux. Do not append /chat/completions, add a Bearer prefix, or enable Azure authentication.

3. **Choose the exact model**
   Enter MODEL_ID_FROM_CATALOG after replacing it with the ID available to your key. If your version has separate Plan and Act model selectors, configure the intended provider/model for both modes.

4. **Set capabilities carefully**
   Use the documented context and output limits for your chosen model. Enable image or tool features only when that model supports them. Keep automatic approval off for your first task.

5. **Save and open a fresh task**
   Save the settings, confirm the provider and model shown by Cline, then start a new task. If the old selection persists, reopen Cline or reload the editor. Keep keys in Cline's credential UI, not a project settings file.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- API key: Your Luma Cloud key, entered in the client's secret field

- Model ID: MODEL_ID_FROM_CATALOG

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Optional agent check

```text
Read README.md in this test folder and summarize its first paragraph. Do not edit files, run shell commands, or access the network.
```

Create a disposable folder containing a short README.md first. Approve only the file read. Check that a tool result and a final answer both appear.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

## Limits

- This configures Cline, not the editor's built-in assistant or autocomplete.

- A successful connection check does not confirm every agent feature. Verify tools and images separately when you need them.

- Client cost estimates may differ from the amount recorded in Dashboard → API.

## Troubleshooting

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### Model not found or access denied

Copy the exact model ID available to this key from the authenticated catalog. MODEL_ID_FROM_CATALOG is a placeholder, not a model name. Do not substitute a display label or copy an ID from another provider.

### Text works, but the task stops at a tool call

Select a model with native tool calling and use the small file-read check. A text response or a successful Verify button is not enough to qualify an agent workflow. Share the error and model ID with support, without your key.

### The wrong model runs after switching modes

Check Cline's Plan and Act selections separately if your version exposes both. Start a new task after correcting them and confirm the displayed model before sending.

### The request is limited or cannot be funded

Read the error message and check the key's balance or subscription quota in the dashboard. Wait for the stated retry time when provided. Repeatedly creating keys or re-entering the same credentials does not add quota.

## Official client documentation

- [Cline: OpenAI Compatible](https://docs.cline.bot/provider-config/openai-compatible)

- [Cline: configuration locations](https://docs.cline.bot/getting-started/config)

---

# Kilo Code + Luma Cloud

Create a named Luma Cloud provider and select models from your API catalog.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Install the Kilo Code extension.

## Setup

1. **Add a custom provider**
   Open Settings → Providers → Custom provider. Set a new provider ID, such as luma-cloud, and display name Luma Cloud.

2. **Choose the protocol**
   Select OpenAI Compatible for Chat Completions. Enter the Base URL and Luma Cloud API key.

3. **Add your models**
   Choose from the fetched model list, or enter the exact catalog ID manually. The display name can be Luma Cloud; the model ID must remain unchanged. Match model limits and capabilities to the selected model, then submit the provider.

4. **Keep credentials local**
   Use Kilo's API key field on macOS, Windows, or Linux. If you edit configuration files, keep credentials separate and never put a key in a shared project config or settings export. An exported Kilo configuration can contain secrets.

5. **Select the provider for a new task**
   Choose the new Luma Cloud model from Kilo's picker. Check the model again when changing profiles or task modes. Reopen the extension if the new provider is not visible after saving.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- API key: Your Luma Cloud key, entered in the client's secret field

- Model ID: MODEL_ID_FROM_CATALOG

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Optional agent check

```text
Read README.md in this test folder and summarize its first paragraph. Do not edit files, run shell commands, or access the network.
```

Create a disposable folder containing a short README.md first. Approve only the file read. Check that a tool result and a final answer both appear.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

## Limits

- Choose OpenAI Responses only for a model and workflow that support that API. Do not select Anthropic Messages for Luma Cloud.

- Model discovery does not establish tool, image, or reasoning support. Match advanced settings to the selected model.

- Adding Luma Cloud does not replace your existing provider configurations.

## Troubleshooting

### Automatic model detection returns no models

Check that Base URL is exactly https://api.lumaos.cloud/v1 and that the key is active. Try entering an ID from your authenticated catalog manually. An empty discovery list does not justify using another account's model ID.

### A request reports the wrong endpoint or protocol

For this guide choose OpenAI Compatible / Chat Completions. OpenAI Responses is a separate selection. The protocol, base URL, and model must describe the same connection; remove any stale full endpoint suffix.

### Settings return after you change them

Open Local Config and Global Config from Kilo settings and check which file supplies the value. Project configuration can override your global setup. Back up the affected file and change only the Luma Cloud entry.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### The request is limited or cannot be funded

Read the error message and check the key's balance or subscription quota in the dashboard. Wait for the stated retry time when provided. Repeatedly creating keys or re-entering the same credentials does not add quota.

## Official client documentation

- [Kilo Code: custom OpenAI-compatible providers](https://kilo.ai/docs/ai-providers/openai-compatible)

- [Kilo Code: settings, config files, and exports](https://kilo.ai/docs/getting-started/settings)

---

# Roo Code + Luma Cloud

Use the OpenAI Compatible provider with a model that supports native tool calling.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Install Roo Code and choose a model with OpenAI-compatible native tool calling.

## Setup

1. **Open Roo's provider settings**
   Open the Roo Code sidebar and its settings gear. Select OpenAI Compatible as the API Provider. If you already use a profile, preserve it and configure Luma Cloud separately where your version supports profiles.

2. **Set URL, key, and model**
   Use https://api.lumaos.cloud/v1 as Base URL and the exact catalog model ID. Enter the key in Roo's API Key field on macOS, Windows, or Linux. Do not put the key in repository settings or add Authorization headers manually.

3. **Check model capabilities**
   Use a model with native tool calling. Set context and output limits from its details; do not guess them from the model name. Leave image/computer-use features off unless supported.

4. **Save the selection**
   Save, select the Luma Cloud configuration, and create a new task. Check the active model before sending. If the previous model remains selected, reopen Roo or reload the editor.

5. **Start a small task**
   Select the new configuration and ask Roo to read one harmless file. Review requested actions before allowing edits or commands.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- API key: Your Luma Cloud key, entered in the client's secret field

- Model ID: MODEL_ID_FROM_CATALOG

## Optional agent check

```text
Read README.md in this test folder and summarize its first paragraph. Do not edit files, run shell commands, or access the network.
```

Create a disposable folder containing a short README.md first. Approve only the file read. Check that a tool result and a final answer both appear.

## Verify

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

- Confirm a completed task and matching API usage. If text works but tool calls fail, the integration is not ready for Roo agent tasks.

## Limits

- Roo's documented tool protocol is native tool calling only. There is no XML fallback for a model without tools.

- Do not enable vision or computer-use options unless the chosen model supports them.

- Local token prices are estimates; Dashboard → API records Luma Cloud charges.

## Troubleshooting

### The model answers in prose instead of calling a tool

Use a model documented to support native tool calling. Roo has no XML fallback. Retry only the read-only check after correcting the model; do not work around it by granting broader permissions.

### Context or output-token validation fails

Compare Roo's Model Configuration limits with the selected model's actual limits. Reduce the output budget or shorten the task. Do not copy token limits from an unrelated model.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### Model not found or access denied

Copy the exact model ID available to this key from the authenticated catalog. MODEL_ID_FROM_CATALOG is a placeholder, not a model name. Do not substitute a display label or copy an ID from another provider.

### The request is limited or cannot be funded

Read the error message and check the key's balance or subscription quota in the dashboard. Wait for the stated retry time when provided. Repeatedly creating keys or re-entering the same credentials does not add quota.

## Official client documentation

- [Roo Code: OpenAI-compatible providers and tool requirements](https://roocodeinc.github.io/Roo-Code/providers/openai-compatible/)

---

# VS Code · Chat & Copilot + Luma Cloud

Add Luma Cloud with VS Code's Custom Endpoint model provider.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Use a VS Code version with Custom Endpoint. Organization policy may restrict bring-your-own-key models.

## Setup

1. **Open the native model manager**
   Open the Command Palette with Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux. Run Chat: Manage Language Models. This configures VS Code Chat itself; Continue, Cline, and other extensions have their own settings.

2. **Add Luma Cloud**
   Choose Add Models → Custom Endpoint and name the group Luma Cloud. Enter your API key in the prompt. Let VS Code retain the secret reference; do not paste the raw key into a project settings file.

3. **Configure the model**
   Choose Chat Completions. In the generated chatLanguageModels.json, set the model ID and full endpoint below. Retain the generated ${input:...} secret reference. Set input/output limits and tool/vision flags from the model's supported capabilities.

4. **Select it in chat**
   Save and choose the Luma Cloud model in a new chat. Agent mode requires tool calling. If the model is absent, reload VS Code and check the organization policy.

## Connection fields

- Provider: Custom Endpoint

- API type: chat-completions

- Model URL: https://api.lumaos.cloud/v1/chat/completions

- Model ID: MODEL_ID_FROM_CATALOG

## Optional model discovery — provider entry in chatLanguageModels.json

```json
[
  {
    "name": "Luma Cloud",
    "vendor": "customendpoint",
    "apiKey": "${input:lumaCloudApiKey}",
    "apiType": "chat-completions",
    "url": "https://api.lumaos.cloud/v1"
  }
]
```

Use this inside the file opened by VS Code, preserving other providers. Replace ${input:lumaCloudApiKey} with the secret reference generated by your own Add Models flow. Provider-level url requests model discovery; an explicitly configured model instead needs the full /chat/completions URL and its real token limits. Do not use both approaches for the same entry.

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

## Limits

- Current VS Code supports BYOK chat without a Copilot plan. Inline suggestions, semantic search, and embeddings have separate requirements.

- Agent Host BYOK is experimental. This guide does not replace its separate setup.

- The old customOAIModels setting is deprecated. For Responses, use the matching API type and /responses URL.

## Troubleshooting

### Custom Endpoint is missing

Check your VS Code version and organization BYOK policy. Do not paste the old github.copilot.chat.customOAIModels setting into a newer setup. If native setup is unavailable, use the separate Continue guide.

### The model is visible in Chat but not Agent

Agent mode filters for tool-calling models. Check real model support before enabling toolCalling. A provider display name alone cannot add tool support.

### The URL returns 404

Check the field you are editing. A provider-level discovery url uses https://api.lumaos.cloud/v1; a model-level url uses https://api.lumaos.cloud/v1/chat/completions. Do not repeat /v1 or append /models to the model inference URL.

### Context usage or generation limits look wrong

Check maxInputTokens and maxOutputTokens. Their sum must not exceed the model's context window. Preserve the generated secret reference when editing these numbers.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

## Official client documentation

- [VS Code: language models and Custom Endpoint](https://code.visualstudio.com/docs/agent-customization/language-models)

---

# JetBrains AI Assistant + Luma Cloud

Use Luma Cloud in AI Assistant across supported IntelliJ-based IDEs.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Install AI Assistant in a supported JetBrains IDE. Your organization must allow third-party providers.

## Setup

1. **Open providers**
   Go to Settings → Tools → AI Assistant → Providers & API keys. In Third-party AI providers, choose OpenAI-compatible.

2. **Enter the endpoint and key**
   Use https://api.lumaos.cloud/v1 as the provider API URL. Paste the Luma Cloud key in the API Key field on macOS, Windows, or Linux. Use the IDE's credential field rather than committing a key to .idea files.

3. **Check the connection**
   Click Test Connection. Enable Tool calling only when supported by the selected model. A connection check confirms access, while the first chat request below checks an actual answer.

4. **Assign the model**
   Choose the catalog model in AI Chat and, where needed, Models Assignment. Set Core features and Instant helpers deliberately; keep any existing assignments you still want.

5. **Apply and start a new chat**
   Click Apply to save. Open AI Chat, select the intended model, and send the first request below. If the picker still shows the old provider, reopen AI Chat or restart the IDE after saving your work.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- API key: Your Luma Cloud key, entered in the client's secret field

- Model ID: MODEL_ID_FROM_CATALOG

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Try an AI Chat answer, then separately check any in-editor action or MCP tool you intend to use.

## Limits

- Applies to AI Assistant. Integrated Junie, Codex, and other agents have separate model/authentication requirements.

- Inline completion and next-edit suggestions need FIM or edit-prediction models and separate AI Completion configuration. A chat model does not automatically support them.

- When JetBrains AI remains enabled, unsupported features may use its models. Check the selected model before comparing usage.

## Troubleshooting

### The provider option is missing or disabled

Check that AI Assistant is installed, enabled, and up to date. Managed IDEs can restrict third-party keys. Ask your administrator about that setting or use the separate Continue extension guide when permitted.

### Test Connection succeeds but an editor action is unavailable

Review Models Assignment for that feature. A chat connection does not automatically provide every AI Assistant feature, and integrated agents have separate setup.

### Inline completion still uses another model

AI Completion is configured separately from Third-party AI providers. It needs FIM or edit-prediction support; do not assign a general chat model just because its ID is visible.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### Model not found or access denied

Copy the exact model ID available to this key from the authenticated catalog. MODEL_ID_FROM_CATALOG is a placeholder, not a model name. Do not substitute a display label or copy an ID from another provider.

## Official client documentation

- [JetBrains: third-party models, assignments, and feature limits](https://www.jetbrains.com/help/ai-assistant/use-custom-models.html)

---

# Zed + Luma Cloud

Add Luma Cloud as a separate provider for Zed's own AI features.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Use a Zed version with custom OpenAI-compatible providers.

## Setup

1. **Add the provider**
   Run agent: open settings. Under LLM Providers, choose Add Provider and OpenAI-compatible. Name it Luma Cloud.

2. **Enter model details**
   Set the API URL and model ID below. Enter the model's supported context window. Use the provider settings key field; Zed stores the key in the system keychain.

3. **Select capabilities**
   Select the new model. Match tool and image settings to its actual capabilities. For a Responses-only model, set capabilities.chat_completions to false; otherwise use Chat Completions.

4. **Start with the Zed Agent**
   Save the provider and select its model in a new Zed Agent conversation. Do not select an external ACP agent for this check. If you changed an environment-provided key, restart Zed so the local app receives the updated environment.

## Connection fields

- API URL: https://api.lumaos.cloud/v1

- Model ID: MODEL_ID_FROM_CATALOG

- Key storage: Provider settings → system keychain

## Settings template — merge into your existing language_models object

```json
{
  "language_models": {
    "openai_compatible": {
      "luma-cloud": {
        "api_url": "https://api.lumaos.cloud/v1",
        "available_models": [
          {
            "name": "MODEL_ID_FROM_CATALOG",
            "display_name": "Luma Cloud",
            "max_tokens": "REPLACE_WITH_CONTEXT_WINDOW_INTEGER",
            "capabilities": {
              "tools": false,
              "images": false,
              "chat_completions": true
            }
          }
        ]
      }
    }
  }
}
```

This is a template, not a ready-to-save model definition. Replace the model ID and replace the entire quoted context placeholder with the model's numeric context window, without quotes. Enable tools only for a model that supports them before using Zed Agent. Leave your key out of this file; enter it in provider settings on macOS, Windows, or Linux.

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Optional agent check

```text
Read README.md in this test folder and summarize its first paragraph. Do not edit files, run shell commands, or access the network.
```

Create a disposable folder containing a short README.md first. Approve only the file read. Check that a tool result and a final answer both appear.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

## Limits

- Zed's edit prediction has its own configuration. This connection covers model-backed chat, Inline Assistant, and similar Zed features.

- External agents configure their own API connection; they do not inherit this provider automatically.

- Do not place API keys in settings.json. Existing provider environment variables can override saved keys.

## Troubleshooting

### The settings file reports a type error

Replace the quoted context placeholder with an integer. Merge the provider into the existing language_models and openai_compatible objects instead of adding duplicate keys. Using the Add Provider UI avoids manual JSON editing.

### A saved key is ignored

For provider ID luma-cloud, a non-empty LUMA_CLOUD_API_KEY environment variable overrides the saved key. Remove or correct that value and restart Zed. Remote-project model calls still use the local Zed app's credentials.

### An external agent asks you to sign in

This provider config belongs to Zed's own AI features. An ACP agent such as OpenCode uses its own configuration and credentials; follow that agent's guide.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### Model not found or access denied

Copy the exact model ID available to this key from the authenticated catalog. MODEL_ID_FROM_CATALOG is a placeholder, not a model name. Do not substitute a display label or copy an ID from another provider.

## Official client documentation

- [Zed: API access and OpenAI-compatible endpoints](https://zed.dev/docs/ai/use-api-access)

---

# Cursor + Luma Cloud

A conditional chat connection using Cursor's OpenAI base URL override.

API connection: Check client requirements. 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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Your Cursor version must expose Override OpenAI Base URL and accept the chosen model. Save your existing endpoint settings before changing them.

## Setup

1. **Check the override**
   Open Cursor Settings → Models → API Keys. Find OpenAI API Key and Override OpenAI Base URL. This override can affect other models; use a dedicated setup if you need to preserve them.

2. **Set the URL and credential together**
   In that same Models panel, paste the Luma Cloud API key into OpenAI API Key and set the enabled Base URL override to https://api.lumaos.cloud/v1. Use the API Key field on macOS, Windows, or Linux. Do not put credentials in .cursor/rules or workspace settings.

3. **Add and select a compatible model**
   If your version offers Add model, enter the exact catalog ID and enable it. Click Save for the API settings. Start a fresh chat and explicitly select that model; an automatic or built-in model selection is not evidence that Luma Cloud is being used.

4. **Test one chat request**
   Send the example below. If Cursor rejects the model, the conditional connection is not usable with that model/version. Do not rename a model to impersonate a supported one. Continue or Cline inside a supported editor can be configured independently using their own guide.

5. **Return to your earlier setup when needed**
   Restore the original Base URL override state and provider credential in Models, save, and start a new conversation. Avoid leaving a Luma key paired with the official OpenAI URL, or an OpenAI key paired with the Luma Cloud URL.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- API key: Your Luma Cloud key, entered in the client's secret field

- Model ID: MODEL_ID_FROM_CATALOG

## First chat request

```text
Reply with exactly: Luma Cloud connection works.
```

Send this in a new conversation with the Luma Cloud model selected. This is a normal API request and uses the selected key's balance or quota.

## Verify

- Send a short text request, then check Usage → API Wallet for Wallet usage, or subscription Usage for Builder keys. A populated model list alone does not confirm a successful response.

- Check that any existing provider you keep using still works after changing the global override.

## Limits

- Cursor documents BYOK for chat and limits its OpenAI support to standard non-reasoning chat models. Reasoning and agent workflows are not guaranteed.

- Tab completion still uses Cursor's own models.

- Cursor sends BYOK requests through its backend for prompt preparation. This is not a direct-only connection from your computer.

## Troubleshooting

### Override OpenAI Base URL is not available

Check the installed Cursor version and current API settings UI. There is no documented universal Cursor config file to paste here. Use an independently configured extension or another supported client rather than modifying Cursor's application files.

### The API works elsewhere but Cursor rejects the model

Cursor's native BYOK model support is narrower than general OpenAI-compatible API support. Test a permitted non-reasoning chat model. If it still fails, restore the original settings and use the OpenCode, Continue, or Cline guide.

### An unrelated model stopped working

The Base URL override can apply beyond the custom model. Restore the saved endpoint and matching key together. Prefer a separately configured extension when you need simultaneous providers without changing the shared override.

### Tab or Agent does not follow the selected API key

This conditional setup is for native chat. Tab remains a Cursor feature, and reasoning/agent support is not established by a successful chat request.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

## Official client documentation

- [Cursor: BYOK scope and handling](https://cursor.com/help/models-and-usage/api-keys)

- [Cursor support: base URL override fields](https://forum.cursor.com/t/openai-api-key-and-override-openai-base-url-cant-be-modified/167982/5)

- [Cursor support: global override limitation](https://forum.cursor.com/t/can-the-api-key-and-base-url-corresponding-to-a-custom-model-be-set-separately-when-adding-a-cursor/137108)

---

# Windsurf / Devin Desktop + Luma Cloud

Use a separately configured OpenCode agent through ACP where your editor plan supports it.

API connection: Check client requirements. 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

- Follow the OpenCode guide first and confirm that its Luma Cloud connection works.

- Use a Devin Desktop build with ACP support. Its documentation lists Pro, Max, and Teams access; enterprise users need administrator enablement.

## Setup

1. **Configure OpenCode first**
   Keep the Luma Cloud key and provider configuration in OpenCode. Do not paste a Luma key into an unrelated built-in provider field.

2. **Register the external agent**
   Run Open Local ACP Registry Config and merge the OpenCode entry from the official ACP guide with your existing registry. The OpenCode executable must already be installed; the editor does not download it from the registry.

3. **Use the executable on this computer**
   In distribution.binary, use the entry matching your operating system and processor. Set cmd to the real installed OpenCode executable, with acp as its argument. The registry file is ~/.windsurf/acp/registry.json on macOS/Linux; on Windows open it through the Command Palette to select the active profile's file.

4. **Enable and select OpenCode**
   Open Devin User Settings → Agents, enable the agent, then restart. Select OpenCode for a new conversation and choose its configured Luma Cloud model.

5. **Keep the API key in OpenCode**
   Use the credentials configured in the OpenCode guide. If the editor cannot see an environment-only key, use the agent's local credential setup. Never place a raw key in a shared ACP registry; the registry describes how to start an agent.

## macOS Apple Silicon — binary entry inside an OpenCode registry definition

```json
{
  "darwin-aarch64": {
    "archive": "",
    "cmd": "/ABSOLUTE/PATH/TO/opencode",
    "args": [
      "acp"
    ]
  }
}
```

This is only the distribution.binary entry, not a complete registry. Merge it into the OpenCode definition from the official ACP guide and replace the executable placeholder. Use darwin-x86_64 for an Intel Mac, or the corresponding linux platform key on Linux.

## Windows x64 — binary entry inside an OpenCode registry definition

```json
{
  "windows-x86_64": {
    "archive": "",
    "cmd": "C:\\PATH\\TO\\opencode.exe",
    "args": [
      "acp"
    ]
  }
}
```

Replace the path with the actual executable. Use windows-aarch64 on ARM Windows when supported by your installed agent. Keep the surrounding registry and other agents intact.

## Optional agent check

```text
Read README.md in this test folder and summarize its first paragraph. Do not edit files, run shell commands, or access the network.
```

Create a disposable folder containing a short README.md first. Approve only the file read. Check that a tool result and a final answer both appear.

## Verify

- Confirm that the conversation is running OpenCode, then complete a short task and check API usage.

- If the agent cannot find its key, configure its local secret/environment through the agent settings; keep secrets out of shared registry files.

## Limits

- The current Windsurf docs redirect to Devin Desktop. They do not document a general Luma Cloud Base URL setting for built-in Cascade or Tab.

- ACP runs a separate agent; it does not replace the built-in assistant's models or billing.

- Older Windsurf builds without this ACP integration need a separately supported client, such as OpenCode.

## Troubleshooting

### The ACP agent controls are missing

Confirm your editor build and plan support ACP. Older Windsurf versions may not expose this integration. OpenCode can still be used separately; adding a registry file alone does not add missing editor functionality.

### The agent is listed but cannot start

Confirm OpenCode is installed and the registry cmd points to its actual executable for your OS and architecture. The editor does not install archive URLs from the registry. Re-enable the agent and restart after correcting the entry.

### OpenCode works in Terminal but has no key in the editor

The GUI app may not inherit the terminal environment. Configure OpenCode's local credentials as described in its guide, or the agent-specific local environment in Devin User Settings → Agents. Do not add the key to a team registry.

### The built-in assistant is still selected

Start a new conversation and choose OpenCode from the agent selector. ACP configuration does not change Cascade or Tab. If all agents are disabled, inspect the workspace's Restricted Mode and enable trust only for a folder you trust.

## Official client documentation

- [Windsurf / Devin Desktop: models](https://docs.devin.ai/desktop/models)

- [Devin Desktop: ACP and OpenCode setup](https://docs.devin.ai/desktop/acp)

---

# OpenCode + Luma Cloud

Add Luma Cloud alongside your existing providers in OpenCode's classic configuration.

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 portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.

- This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.

- Choose either an environment secret or OpenCode's local credential prompt below. Never paste the key into a chat, shared config, or Git.

- Use a small test project with a README.md that contains no private information for your first connection.

## Setup

1. **Check your version and configuration format**
   Run opencode --version and inspect the existing config. This example uses the classic provider / npm / options format. For a native V2 providers / package / settings entry, use the V2 guide. V2 also accepts supported classic settings; connecting Luma Cloud does not require a migration.

2. **Open the right file**
   For this project, edit opencode.json or opencode.jsonc in its root. For all projects, use ~/.config/opencode/opencode.json; JSONC is also supported. Keep the existing file and make a backup. If you already use OPENCODE_CONFIG, inspect that file too: project settings can override it. Choose one scope for the Luma entry.

3. **Choose how to provide the key**
   The snippet reads LUMA_CLOUD_API_KEY from the environment. Load your Dashboard → API key through a secret manager or the private prompt in Quickstart, then start OpenCode from that shell. Alternatively, in classic OpenCode use /connect → Other, enter provider ID luma-cloud, and paste the key into its credential prompt. For that alternative, omit only options.apiKey from the snippet so OpenCode uses the saved credential.

4. **Merge the provider and exact model ID**
   If provider already exists, insert only its luma-cloud child shown below; do not paste a second provider key or a second root object. If luma-cloud already exists, update its relevant fields. Keep other providers, defaults, plugins, and permissions. Replace MODEL_ID_FROM_CATALOG with an exact ID from GET /v1/models, keeping the quotes.

5. **Reopen and select Luma Cloud**
   Save valid JSON or JSONC. When current tasks finish, close and reopen OpenCode in this project, then start a new session. Run /models and select luma-cloud/MODEL_ID_FROM_CATALOG. A desktop app or a server already running elsewhere does not inherit a variable newly set in your terminal; use its credential prompt or configure the environment of the process making requests.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- Provider ID: luma-cloud

- Model selection: luma-cloud/MODEL_ID_FROM_CATALOG

## Merge into opencode.json(c)

```json
{
  "provider": {
    "luma-cloud": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Luma Cloud",
      "options": {
        "baseURL": "https://api.lumaos.cloud/v1",
        "apiKey": "{env:LUMA_CLOUD_API_KEY}"
      },
      "models": {
        "MODEL_ID_FROM_CATALOG": {
          "name": "Luma Cloud model"
        }
      }
    }
  }
}
```

For a new empty file, use this whole object. In an existing file, merge the luma-cloud child into provider without duplicating keys. Leave the environment reference literal; replace only the model placeholder. The luma-cloud/ selection prefix is local to OpenCode.

## macOS / Linux · Bash or Zsh · private key input

```bash
printf 'Luma Cloud API key: ' >&2
read -r -s LUMA_CLOUD_API_KEY
printf '\n' >&2
export LUMA_CLOUD_API_KEY
```

Run in an interactive terminal, paste the key at the hidden prompt and press Enter. The value is available to programs launched from this terminal, not apps already running. Do not enable shell tracing. After closing the client, unset LUMA_CLOUD_API_KEY to remove it from this shell.

## Windows · PowerShell · private key input

```powershell
$lumaSecret = Read-Host 'Luma Cloud API key' -AsSecureString
try {
  $env:LUMA_CLOUD_API_KEY = [System.Net.NetworkCredential]::new('', $lumaSecret).Password
} finally {
  $lumaSecret.Dispose()
  Remove-Variable lumaSecret
}
```

The key becomes a process environment value without being printed or included in the command. Start the client from this PowerShell window. Remove-Item Env:LUMA_CLOUD_API_KEY clears it after you close the client; do not use setx to make the secret global.

## Start from the project containing opencode.json(c)

```sh
opencode --version
opencode --model luma-cloud/MODEL_ID_FROM_CATALOG
```

Works in a terminal on macOS, Linux or Windows with OpenCode on PATH. Replace the placeholder in both the config and command. Use your editor to create or merge the file; do not redirect this fragment over an existing file. If you use WSL, edit the file inside the project opened by that WSL process.

## Inside OpenCode · select and verify

```text
/models
Reply with: Luma connection ready.
```

Select the luma-cloud model in the picker before sending the second line. That message makes one billable request. /connect → Other is an alternative to environment credentials; use provider ID luma-cloud and omit options.apiKey only for that alternative.

## Verify

- Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.

- For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

- Then ask: "Read README.md using the file-read tool and summarize its purpose. Do not edit files or run shell commands." Inspect the completed read tool result and answer; a text reply alone does not verify tools. Keep permission prompts enabled and decline edits or shell execution during this check.

## Limits

- The shown adapter uses Chat Completions. For a Responses configuration, the classic OpenCode docs specify @ai-sdk/openai; do not mix the two schemas.

- Tool use and context limits depend on the selected model. Add capability or context overrides only when the model's documentation supports them.

## Troubleshooting

### Luma Cloud does not appear in /models

Check that the key under provider is luma-cloud and the models object contains an exact ID from your authenticated catalog. Confirm you started in the folder with the edited config. A project config or OPENCODE_CONFIG can override another file; edit one intended scope and keep the others intact.

### Configuration fails to parse

Classic configuration uses provider / npm / options. V2 native configuration uses providers / package / settings. Do not mix both formats inside one entry or create duplicate provider keys. Fix the reported syntax location before restarting.

### Terminal works, desktop or remote session returns 401

A desktop launch or remote server does not inherit this terminal's secret. Use that client's supported credential prompt, or supply the variable to the process making API requests. Do not print the key to inspect it or replace another provider's credentials.

### The model is listed but the request fails

Check the exact ID against GET /v1/models with the same key, then read the response code. 402 means check this key's Wallet or Builder quota; 429 means wait as instructed and reduce concurrent tasks. Keep the request ID for support.

## Official client documentation

- [OpenCode: custom providers](https://opencode.ai/docs/providers/#custom-provider)

- [OpenCode: configuration and environment references](https://opencode.ai/docs/config/)

- [OpenCode: CLI and version flag](https://opencode.ai/docs/cli/)

- [OpenCode V2: supported classic configuration](https://opencode.ai/v2/docs/migrate-v1/)

---

# OpenCode V2 + Luma Cloud

Use the V2 provider format without replacing your current OpenCode setup.

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 portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.

- This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.

- Load LUMA_CLOUD_API_KEY from your secret manager or a private environment before starting the client. Never put the key in a prompt, Git, or a shared configuration file.

- Use a small test project with a README.md that contains no private information for your first connection.

## Setup

1. **Check the installed version first**
   Run opencode --version. This recipe uses V2's native providers / package / settings format. V1 needs the classic guide. V2 can also read supported classic provider / npm / options settings, so preserve working entries rather than converting the entire file. Keep each individual provider entry in one format.

2. **Find your active configuration**
   Use the existing project opencode.json or opencode.jsonc, or the corresponding file in <project>/.opencode/. Global settings live at ~/.config/opencode/opencode.json or opencode.jsonc. Back up the file, then edit one scope. Project and .opencode settings are merged and can override global settings; avoid adding competing copies of the same provider.

3. **Merge the native V2 provider**
   When providers already exists, add only its luma-cloud child shown below. Do not add another providers key or overwrite the whole file. Update an existing luma-cloud entry in place. Replace both occurrences of MODEL_ID_FROM_CATALOG with the same exact ID from GET /v1/models. Keep existing defaults, plugins, and permissions.

4. **Pass the key to the process making requests**
   Use the private prompt in Quickstart or your secret manager to export LUMA_CLOUD_API_KEY in your shell. The env array contains the variable's name, never the key. For a first terminal check, run opencode --standalone from the project in that shell: its private server receives that environment. Opening another client against an existing background server does not pass it your new shell variable.

5. **Connect a desktop or shared-server client**
   For an existing server, arrange the variable in that server's managed environment and restart it normally once its tasks finish. Alternatively, after loading the provider configuration, open /connect and select Luma Cloud if that integration offers API-key entry; enter the key only in the credential prompt. Saved accounts take precedence over environment credentials. Do not paste a secret into settings.baseURL or the chat.

6. **Choose the model in a new session**
   Save valid JSON or JSONC, reopen the project after configuration reload, and start a new session. Use /models to choose luma-cloud/MODEL_ID_FROM_CATALOG. This guide does not write a global default model. If the model is missing, check which server and project you opened, the provider spelling, and configuration errors before changing other settings.

## V2: merge into opencode.jsonc

```json
{
  "providers": {
    "luma-cloud": {
      "name": "Luma Cloud",
      "env": [
        "LUMA_CLOUD_API_KEY"
      ],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://api.lumaos.cloud/v1"
      },
      "models": {
        "MODEL_ID_FROM_CATALOG": {
          "modelID": "MODEL_ID_FROM_CATALOG",
          "name": "Luma Cloud model"
        }
      }
    }
  }
}
```

For a new empty file, use the whole object; otherwise merge only the luma-cloud child under providers. Replace both model placeholders with the same catalog ID. Keep LUMA_CLOUD_API_KEY as a variable name, not a secret value.

## macOS / Linux · Bash or Zsh · private key input

```bash
printf 'Luma Cloud API key: ' >&2
read -r -s LUMA_CLOUD_API_KEY
printf '\n' >&2
export LUMA_CLOUD_API_KEY
```

Run in an interactive terminal, paste the key at the hidden prompt and press Enter. The value is available to programs launched from this terminal, not apps already running. Do not enable shell tracing. After closing the client, unset LUMA_CLOUD_API_KEY to remove it from this shell.

## Windows · PowerShell · private key input

```powershell
$lumaSecret = Read-Host 'Luma Cloud API key' -AsSecureString
try {
  $env:LUMA_CLOUD_API_KEY = [System.Net.NetworkCredential]::new('', $lumaSecret).Password
} finally {
  $lumaSecret.Dispose()
  Remove-Variable lumaSecret
}
```

The key becomes a process environment value without being printed or included in the command. Start the client from this PowerShell window. Remove-Item Env:LUMA_CLOUD_API_KEY clears it after you close the client; do not use setx to make the secret global.

## Find the configuration directory and start a private server

```sh
opencode --version
opencode debug paths config
opencode --standalone
```

Run from the project containing opencode.json(c), using the same terminal where you entered the key. debug paths reports this installation's real directory on macOS, Linux and Windows. Standalone mode gives this client its own server; it does not replace or stop your shared server.

## Inside OpenCode V2 · select before sending

```text
/models
Reply with: Luma connection ready.
```

Choose luma-cloud/MODEL_ID_FROM_CATALOG before the test message. The map key is the local selection name; modelID is the ID sent to Luma. This recipe keeps both identical to avoid confusing aliases.

## Verify

- Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.

- For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

- Then ask: "Read README.md using the file-read tool and summarize its purpose. Do not edit files or run shell commands." Verify the completed read tool result as well as the answer. Leave permission prompts enabled; decline edits or shell execution for this check.

## Limits

- This recipe uses Chat Completions. V2 documents a separate @opencode/ai/providers/openai-compatible/responses package for Responses.

- Do not copy classic npm/options fields into the V2 providers block. Model capabilities and limits must match the selected model.

## Troubleshooting

### Missing credential although the variable is set

The server performs requests. Start --standalone from this terminal for the first test, or configure the existing server's supported secret mechanism. A saved provider account can take precedence over environment credentials; review the selected Luma account in /connect without logging out other providers.

### Unknown provider fields or runtime package

Confirm the installed version and use one schema per provider. Native V2 needs package and settings; classic uses npm and options. Preserve working classic entries rather than migrating the entire file as part of this connection.

### Model unavailable after editing

Open the same project/server that loaded the file, then inspect /models. Check both the models map key and modelID; replace both placeholders with the actual catalog ID. A second .opencode/opencode.jsonc or global entry can override what you edited.

### Tools or reasoning fail after chat succeeds

Keep the working Chat Completions adapter and record the specific failure. Tool support, effort values and Responses compatibility need separate confirmation for the chosen model. Do not mark all capabilities enabled to make the picker accept it.

## Official client documentation

- [OpenCode V2: providers and custom gateways](https://opencode.ai/v2/docs/providers/)

- [OpenCode V2: configuration locations and merging](https://opencode.ai/v2/docs/config/)

- [OpenCode V2: credentials and server environment](https://opencode.ai/v2/docs/cli/providers)

- [OpenCode V2: standalone and shared server](https://opencode.ai/v2/docs/cli/)

- [OpenCode V2: classic compatibility and native schema](https://opencode.ai/v2/docs/migrate-v1/)

---

# OpenClaw + Luma Cloud

Add a custom Luma Cloud provider and select it for one agent session.

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 portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.

- This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.

- Load LUMA_CLOUD_API_KEY from your secret manager or a private environment before starting the client. Never put the key in a prompt, Git, or a shared configuration file.

- OpenClaw already installed and configured. Run the checks on the machine that hosts your OpenClaw process; a remote web UI does not read files from your laptop.

## Setup

1. **Find the active file and keep a backup**
   Run openclaw config file before editing. The default is ~/.openclaw/openclaw.json, but a profile or OPENCLAW_CONFIG_PATH may select another file. On Windows/WSL, use the path reported by the OpenClaw command in that environment, not a similarly named host folder. Make a private backup and merge only the new provider.

2. **Add the provider**
   Merge luma-cloud under models.providers in ~/.openclaw/openclaw.json. Keep existing entries, channel settings, and agent defaults. Replace MODEL_ID_FROM_CATALOG with the exact Luma model ID.

3. **Connect the secret**
   The example uses an environment SecretRef. For a running service, enter LUMA_CLOUD_API_KEY in its supported secret environment or the private runtime file ~/.openclaw/.env (OPENCLAW_STATE_DIR/.env if customized), then restart that service normally after active work finishes. A key exported in another terminal or stored only in a project's .env is not sufficient. If your default environment secret provider has another name, use that name instead of default.

4. **Validate before opening chat**
   Run openclaw config validate and openclaw models list --provider luma-cloud. Correct schema or secret-reference errors first. A listed model verifies configuration only. Open your normal OpenClaw chat after its configuration has reloaded; do not start a second service over the existing one.

5. **Choose it for a new session**
   In OpenClaw chat, use /model luma-cloud/MODEL_ID_FROM_CATALOG -s. The -s flag keeps the choice within this session. If a model policy blocks it, add this exact model to the existing allowlist without deleting other entries.

## Merge into openclaw.json

```json
{
  "models": {
    "providers": {
      "luma-cloud": {
        "baseUrl": "https://api.lumaos.cloud/v1",
        "api": "openai-completions",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "LUMA_CLOUD_API_KEY"
        },
        "models": [
          {
            "id": "MODEL_ID_FROM_CATALOG",
            "name": "Luma Cloud model",
            "input": [
              "text"
            ]
          }
        ]
      }
    }
  }
}
```

Keep the secret reference as an object; do not replace it with the key. This fragment does not change global defaults or existing fallback lists.

## Inspect and validate · terminal on the OpenClaw machine

```sh
openclaw --version
openclaw config file
openclaw config validate
openclaw models list --provider luma-cloud
```

Run once before editing to record the original state, then validate and list again after saving. These commands do not ask a model to generate a response. Do not share full diagnostic files without checking for private data.

## Inside a new OpenClaw chat · keep the choice session-only

```text
/model luma-cloud/MODEL_ID_FROM_CATALOG -s
/model status
Reply with: Luma connection ready.
```

Replace the placeholder first and send the commands separately. Confirm the selected model before the billable third line. Do not use -g or -a unless you intend to change defaults for other sessions or agents.

## Return this session to its existing default

```text
/model default -s
```

This clears the session choice; it does not delete the Luma provider or change the shared default. For full removal, first move Luma sessions to another model, then remove only the provider entry and its unused secret reference.

## Verify

- Run openclaw models list --provider luma-cloud to inspect configured models. In chat, /model status shows the selected provider and protocol.

- Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.

- For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

## Limits

- openai-completions means Chat Completions in OpenClaw. Use openai-responses only for a model and workflow that support Responses.

- Image, tool, reasoning, and stored-response continuation flags are separate capabilities. Do not enable them merely because the base URL is accepted.

## Troubleshooting

### SecretRef resolution failed

Check the variable exists in the actual OpenClaw runtime environment, and that provider: default matches your environment secret provider. A service does not inherit an export from your current terminal. Keep secrets in the private runtime environment, not a shared workspace file.

### Model exists but selection is blocked

Check the existing agent model policy. Add only luma-cloud/ followed by your exact model ID to the appropriate allowlist if that is your intended policy. Keep other entries and agent defaults; do not replace the full allowlist with this one model.

### Configuration is valid but a request returns 404 or 400

Use the Base URL ending in /v1, not /chat/completions, and api: openai-completions for this recipe. Check the exact model ID and remove unverified capability or reasoning overrides. A valid JSON file does not prove the API parameters are supported.

### Usage comes from a different model or provider

Inspect /model status, the session selection and existing fallback settings. Confirm which request actually completed before comparing usage. Do not change every agent's fallback list to troubleshoot one new Luma session.

## Official client documentation

- [OpenClaw: custom providers](https://docs.openclaw.ai/gateway/config-tools/custom-providers)

- [OpenClaw: environment SecretRefs](https://docs.openclaw.ai/gateway/secrets/secretref-contract)

- [OpenClaw: session model selection](https://docs.openclaw.ai/concepts/models)

- [OpenClaw: active configuration and validation](https://docs.openclaw.ai/cli/config)

- [OpenClaw: runtime environment and private dotenv](https://docs.openclaw.ai/help/environment)

---

# Aider + Luma Cloud

Connect Aider for a single terminal run using its OpenAI-compatible provider.

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 portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.

- This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.

- Load LUMA_CLOUD_API_KEY from your secret manager or a private environment before starting the client. Never put the key in a prompt, Git, or a shared configuration file.

- Aider installed; open a small project you are comfortable testing. Run aider --version and check aider --help for the installed options.

## Setup

1. **Choose the model**
   Copy an exact ID from Luma Cloud's model catalog and replace MODEL_ID_FROM_CATALOG below. Aider requires the openai/ prefix to select its compatible adapter; this prefix is not part of Luma's model ID.

2. **Start a scoped run**
   Run the command from your project in Bash or Zsh. It starts in ask mode with automatic commits disabled. The environment and flags apply only to this run; saved provider defaults stay unchanged.

3. **Check the first reply**
   Ask a short question in this initial session. Switch to an editing mode only when you want file changes; review the diff and run your checks before committing.

4. **Save an optional reusable profile**
   For repeated use, save the YAML example as aider.luma.yml in your project and select it explicitly with --config. It contains no secret. This selects one config file instead of the normal home/project .aider.conf.yml chain, so copy any approval or workflow settings you still need into this separate profile deliberately. Keep the API key in your local environment.

## Bash / Zsh — one Aider run

```bash
OPENAI_API_BASE="https://api.lumaos.cloud/v1" \
OPENAI_API_KEY="${LUMA_CLOUD_API_KEY:?Load LUMA_CLOUD_API_KEY from your secret store first}" \
aider --model openai/MODEL_ID_FROM_CATALOG --chat-mode ask --no-auto-commits --no-dirty-commits
```

The key comes from an existing environment variable. Do not paste the key value into the command.

## macOS / Linux · Bash or Zsh · private key input

```bash
printf 'Luma Cloud API key: ' >&2
read -r -s LUMA_CLOUD_API_KEY
printf '\n' >&2
export LUMA_CLOUD_API_KEY
```

Run in an interactive terminal, paste the key at the hidden prompt and press Enter. The value is available to programs launched from this terminal, not apps already running. Do not enable shell tracing. After closing the client, unset LUMA_CLOUD_API_KEY to remove it from this shell.

## Windows · PowerShell · private key input

```powershell
$lumaSecret = Read-Host 'Luma Cloud API key' -AsSecureString
try {
  $env:LUMA_CLOUD_API_KEY = [System.Net.NetworkCredential]::new('', $lumaSecret).Password
} finally {
  $lumaSecret.Dispose()
  Remove-Variable lumaSecret
}
```

The key becomes a process environment value without being printed or included in the command. Start the client from this PowerShell window. Remove-Item Env:LUMA_CLOUD_API_KEY clears it after you close the client; do not use setx to make the secret global.

## Optional aider.luma.yml · no API key in this file

```yaml
model: openai/MODEL_ID_FROM_CATALOG
openai-api-base: https://api.lumaos.cloud/v1
chat-mode: ask
auto-commits: false
dirty-commits: false
```

Replace the model placeholder. On every OS, the relative path below means the directory where you start Aider. Name it aider.luma.yml so it is used only when you explicitly select it.

## macOS / Linux · run with the separate profile

```bash
OPENAI_API_KEY="${LUMA_CLOUD_API_KEY:?Enter your Luma key first}" aider --config ./aider.luma.yml
```

This assigns OPENAI_API_KEY only to the Aider process. Your shell's existing OpenAI key stays unchanged.

## Windows · PowerShell · run and restore the previous OpenAI environment

```powershell
if (-not $env:LUMA_CLOUD_API_KEY) { throw 'Enter your Luma key first.' }
$lumaPreviousOpenAiKey = [Environment]::GetEnvironmentVariable('OPENAI_API_KEY', 'Process')
try {
  $env:OPENAI_API_KEY = $env:LUMA_CLOUD_API_KEY
  aider --config .\aider.luma.yml
} finally {
  [Environment]::SetEnvironmentVariable('OPENAI_API_KEY', $lumaPreviousOpenAiKey, 'Process')
  Remove-Variable lumaPreviousOpenAiKey
}
```

Save the YAML profile above first. This restores the previous variable after Aider exits, including an originally unset variable. The key never becomes a command-line argument.

## Inside Aider · read one file without editing

```text
/read-only README.md
Summarize the purpose of README.md. Do not edit files or run commands.
```

Use a harmless README in your test project. Aider's read-only file attachment is a client feature; this is not a claim that the model called a remote file tool.

## Verify

- Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.

- For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

## Limits

- Aider may not recognize a custom model's context limit, pricing, or preferred edit format. Use the selected model's documented settings; do not invent token limits to hide a warning.

- Chat compatibility does not guarantee that every model works equally well with Aider's editing workflow.

## Troubleshooting

### Unknown provider or model

Aider needs openai/ before the exact Luma model ID to choose the compatible adapter. The API itself receives the ID without that prefix. Keep the same ID in the profile and command; use the authenticated Luma catalog to check it.

### The request goes to the wrong API

Check the startup model and the selected --config file. For the one-run command, OPENAI_API_BASE must be Luma's Base URL. For the reusable profile, check openai-api-base. Review existing AIDER_* environment overrides locally without dumping secrets.

### 401 despite a working dashboard login

Aider needs a portable API key, not browser login or a desktop token. Enter it locally, then launch from that terminal. In PowerShell, use the try/finally example to avoid replacing your normal OpenAI variable permanently.

### Context, price or edit-format warning

Unknown custom-model metadata does not automatically mean authentication failed. Use the chosen model's documented limits and Aider model settings when available. First verify a short ask-mode reply; only then try an edit on a disposable file and inspect its diff.

## Official client documentation

- [Aider: OpenAI-compatible APIs](https://aider.chat/docs/llms/openai-compat.html)

- [Aider: model and configuration options](https://aider.chat/docs/config/options.html)

- [Aider: ask and editing modes](https://aider.chat/docs/usage/modes.html)

- [Aider: separate YAML configuration files](https://aider.chat/docs/config/aider_conf.html)

- [Aider: read-only files and chat commands](https://aider.chat/docs/usage/commands.html)

---

# Codex CLI + Luma Cloud

Use Luma's Responses API for one CLI session while preserving your normal OpenAI configuration.

API connection: Responses. 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 portable key in Dashboard → API. Use API Wallet credit, or a Builder key when that option is available to your account.

- This is a direct API connection. SuperGPT is not required. Use a named Wallet key on any plan, or a subscription key if your Builder account offers one; your desktop sign-in is not an API key.

- Load LUMA_CLOUD_API_KEY from your secret manager or a private environment before starting the client. Never put the key in a prompt, Git, or a shared configuration file.

- Codex CLI with custom-provider and -c overrides. Check codex --help for your installed version.

## Setup

1. **Choose a Responses model**
   Replace MODEL_ID_FROM_CATALOG with a Responses-capable Luma model and SUPPORTED_EFFORT_FROM_MODEL_DOCS with a reasoning effort that same model supports. The command selects provider, model, and effort together for this run, overriding any saved effort. Chat Completions alone is not enough for current Codex CLI.

2. **Start a separate CLI session**
   Use the command below from your project. Provider settings apply only to this invocation. Do not add them to ~/.codex/config.toml, overwrite your OpenAI provider, log out, or modify ChatGPT/Codex desktop.

3. **Confirm the session**
   Use /status and /debug-config to inspect the active session and configuration layers before the first request. Keep normal sandbox and approval controls enabled. When changing the model, also select an effort supported by the new model. Never use an existing OpenAI conversation as the first compatibility test.

4. **Optional: save a CLI-only named profile**
   Current Codex versions use a separate luma-cli.config.toml beside the user config, selected only with --profile luma-cli. The default location is ~/.codex/luma-cli.config.toml on macOS/Linux and %USERPROFILE%\.codex\luma-cli.config.toml on Windows. If you already use a custom Codex state location, keep it and use its documented profile directory. Create only this named file; do not edit the shared config.toml, auth.json or desktop settings. Codex versions before 0.134.0 use a different profile format: use the one-run command instead of copying this profile into an older format.

## Bash / Zsh — command-scoped provider

```bash
codex \
  --model 'MODEL_ID_FROM_CATALOG' \
  -c 'model_reasoning_effort="SUPPORTED_EFFORT_FROM_MODEL_DOCS"' \
  -c 'model_provider="luma_cloud"' \
  -c 'model_providers.luma_cloud.name="Luma Cloud"' \
  -c 'model_providers.luma_cloud.base_url="https://api.lumaos.cloud/v1"' \
  -c 'model_providers.luma_cloud.env_key="LUMA_CLOUD_API_KEY"' \
  -c 'model_providers.luma_cloud.wire_api="responses"' \
  -c 'model_providers.luma_cloud.requires_openai_auth=false' \
  -c 'model_providers.luma_cloud.supports_websockets=false'
```

First load the key using one of the private input examples below, then replace both model and effort placeholders. No login/logout or persistent provider changes are required. Start Codex without these flags to use your existing defaults again. On Windows, the separate TOML profile below avoids native-command quoting differences.

## macOS / Linux · Bash or Zsh · private key input

```bash
printf 'Luma Cloud API key: ' >&2
read -r -s LUMA_CLOUD_API_KEY
printf '\n' >&2
export LUMA_CLOUD_API_KEY
```

Run in an interactive terminal, paste the key at the hidden prompt and press Enter. The value is available to programs launched from this terminal, not apps already running. Do not enable shell tracing. After closing the client, unset LUMA_CLOUD_API_KEY to remove it from this shell.

## Windows · PowerShell · private key input

```powershell
$lumaSecret = Read-Host 'Luma Cloud API key' -AsSecureString
try {
  $env:LUMA_CLOUD_API_KEY = [System.Net.NetworkCredential]::new('', $lumaSecret).Password
} finally {
  $lumaSecret.Dispose()
  Remove-Variable lumaSecret
}
```

The key becomes a process environment value without being printed or included in the command. Start the client from this PowerShell window. Remove-Item Env:LUMA_CLOUD_API_KEY clears it after you close the client; do not use setx to make the secret global.

## Optional luma-cli.config.toml · Codex 0.134.0 and later

```toml
model = "MODEL_ID_FROM_CATALOG"
model_provider = "luma_cloud"
model_reasoning_effort = "SUPPORTED_EFFORT_FROM_MODEL_DOCS"
web_search = "disabled"

[model_providers.luma_cloud]
name = "Luma Cloud"
base_url = "https://api.lumaos.cloud/v1"
env_key = "LUMA_CLOUD_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
```

This is the whole content of a new dedicated profile, not a replacement for config.toml. Replace model and effort placeholders. Do not wrap these values in [profiles.luma-cli]; current profiles use top-level keys. No API key or OpenAI login is stored in the file.

## Launch the named profile · Bash, Zsh or PowerShell

```sh
codex --version
codex --profile luma-cli --sandbox read-only
```

Run from a disposable project after loading the key. The profile keeps inherited approval settings, while this first session explicitly prevents file writes through the sandbox. Omit --profile luma-cli in a later normal launch to use your existing configuration again.

## Inside the new Codex CLI session

```text
/status
/debug-config
Reply with: Luma connection ready.
```

Inspect the model/provider settings before sending the last line. The last line uses API quota or funds. After it works, ask Codex to read one harmless README and summarize it; approve only the read you expect.

## Verify

- Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.

- For Wallet keys, check Usage → API Wallet for the matching usage. For Builder keys, check subscription Usage. A model in a picker confirms configuration, not a successful response.

- Confirm a completed read-only file operation in the CLI, then its final answer. If only text succeeds, report chat verified and tools not yet verified. Do not enable web search, remote execution or automatic approvals as a connection workaround.

## Limits

- Current official configuration documents wire_api=responses. Do not use older wire_api=chat examples.

- This setup documents the CLI connection, not desktop integration. Built-in web search, remote execution, images, and other optional features need separate support.

## Troubleshooting

### Luma profile is not found or has no effect

Check the CLI version, exact luma-cli.config.toml filename and --profile luma-cli spelling. Current profile files sit beside user config.toml and contain top-level keys. Project-local .codex/config.toml cannot define the custom provider. Use /debug-config to see which file was loaded, without posting its private contents.

### A browser login opens or the OpenAI provider is active

Stop before sending a request and check model_provider=luma_cloud, env_key=LUMA_CLOUD_API_KEY and requires_openai_auth=false in the selected invocation/profile. Do not log out of OpenAI, delete auth.json or copy a desktop token into the environment to fix this.

### 400 for reasoning effort, or a Responses error

Use a model that supports Responses and an effort value supported by that exact model. Replace the effort placeholder instead of inheriting a setting from another model. A working Chat Completions request does not qualify the Responses route; keep wire_api=responses and confirm the correct Base URL.

### Works in one terminal but not another

The environment secret is scoped to the terminal that launched Codex. Enter it again in the intended shell or load it through your secret manager. The named profile contains only a variable reference; it cannot retrieve an environment value from a different running process.

## Official client documentation

- [OpenAI: custom model providers](https://learn.chatgpt.com/docs/config-file/config-advanced)

- [OpenAI: provider configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)

- [OpenAI: CLI flags and named profiles](https://learn.chatgpt.com/docs/developer-commands)

- [OpenAI: inspect active settings](https://learn.chatgpt.com/docs/developer-settings)

---

# Claude Code + Luma Cloud

Direct connection needs Anthropic Messages compatibility, which is not a documented Luma API interface.

API connection: No direct connection. 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

- For a direct Luma connection, choose a client that supports Chat Completions or Responses.

## Setup

1. **Understand the protocol**
   Claude Code treats ANTHROPIC_BASE_URL as an Anthropic-format endpoint and sends Messages requests. Pointing that setting at an OpenAI-compatible base URL does not translate the request.

2. **Choose a direct alternative**
   Use OpenCode, Aider, Cline, or another documented compatible client with a Luma API key. Keep your existing Claude Code login and configuration.

## Verify

- There is no direct Claude Code acceptance test in this guide. Follow the setup and verification steps for the compatible client you choose.

## Limits

- Luma's documented API does not include an Anthropic /v1/messages endpoint. This page does not provide an ANTHROPIC_BASE_URL configuration.

- A third-party protocol translator is a separate integration and requires its own authentication, tools, streaming, and usage validation.

## Troubleshooting

### Changing ANTHROPIC_BASE_URL returns 404

Claude Code is still sending Anthropic Messages. An OpenAI-compatible Base URL cannot change that protocol. Restore only the endpoint override you added, retaining your original Claude configuration and login.

### A Luma key is rejected as an Anthropic key

Do not replace your Anthropic credentials. Create a named Luma API key for a compatible client and follow that client's recipe. Paying for a Luma plan does not authenticate Claude Code to Anthropic.

### A plugin or MCP server offers Luma access

An MCP tool connection is not a replacement for Claude Code's primary model provider. Treat an external translator as a separate integration; this guide does not claim its tools, billing or streaming have been validated.

## Official client documentation

- [Claude Code: gateway protocol requirements](https://code.claude.com/docs/en/llm-gateway-protocol)

- [Claude Code: LLM gateways](https://code.claude.com/docs/en/llm-gateway)

---

# Gemini CLI + Luma Cloud

Gemini CLI's documented connection uses Google services rather than a generic OpenAI-compatible provider.

API connection: No direct connection. 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

- Use a client with a documented OpenAI-compatible custom provider for direct Luma API access.

## Setup

1. **Check the supported connection**
   Gemini CLI documents Google sign-in, a Gemini API key, and Vertex AI. GOOGLE_GEMINI_BASE_URL changes the destination of Gemini-format requests; it does not turn them into Chat Completions or Responses.

2. **Use a compatible agent**
   Choose OpenCode, Aider, or another client in this directory for Luma. Keep your Google login and Gemini CLI settings unchanged.

## Verify

- No direct Luma setup is claimed for Gemini CLI. Verify the alternative client using its own guide.

## Limits

- Do not enter a Luma key as GEMINI_API_KEY or assume that an OpenAI-compatible URL supports Gemini's API format.

- Luma does not document a Gemini/Vertex endpoint. A separate translator would need its own compatibility testing.

## Troubleshooting

### GOOGLE_GEMINI_BASE_URL points to Luma but requests fail

The setting changes where Gemini-format requests go; it does not translate them into Chat Completions. Restore the override you added and use a documented OpenAI-compatible client for Luma.

### GEMINI_API_KEY rejects the Luma key

These keys belong to different services. Keep your Google credentials in Gemini CLI and enter the Luma portable key only in a compatible client's own configuration.

### A Google sign-in or Gemini model picker succeeds

That verifies the Google connection, not Luma billing or API access. For a Luma test, follow the OpenCode or Aider guide and check the matching named key in the Luma dashboard.

## Official client documentation

- [Gemini CLI: authentication methods](https://geminicli.com/docs/get-started/authentication/)

- [Gemini CLI: base URL configuration](https://geminicli.com/docs/reference/configuration/)

---

# Open WebUI + Luma Cloud

Chat with Luma Cloud through an OpenAI-compatible connection.

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.

- Administrator access to your own or a trusted Open WebUI installation.

## Setup

1. **Open connection settings**
   Open Settings → Admin → Connections. In Manage OpenAI API Connections, click + Add Connection. Keep your existing connections.

2. **Fill in the connection**
   Paste https://api.lumaos.cloud/v1 into URL and your Luma key into API Key. Under Advanced, leave Provider at Default.

3. **Limit the model list if needed**
   To show only selected models, enter each exact catalog ID in Model IDs and click +. Leave this list empty to use automatic discovery.

4. **Save and select**
   Click Save and make sure the connection is enabled. Open a new chat, then choose your Luma model in the model selector.

5. **Send your first message**
   Type “Reply with hello.” Start with text only; add files or tools after the basic connection works.

## Connection fields

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

- API Key: Your Luma Cloud API key

- Provider: Default

- Model IDs: Optional filter: MODEL_ID_FROM_CATALOG

- Connection: Enabled

## Verify

- Wait for a completed text reply. Verify Connection checks the model list; it does not send your test message.

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

- If background titles or suggestions fail, check that their configured model is available to this same key.

## Limits

- An administrator connection may be available to other users of that installation. Configure access before saving a personal key.

- This setup is for text chat. Document embeddings, image generation, speech and browser-direct connections need their own compatible setup; they are not enabled by adding this connection.

- Tools and background tasks can make additional model requests. Test one tool at a time after text chat succeeds, with a model that supports tool calling.

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

### The connection saves, but no model appears

Enable the connection and reload the chat model selector. If you added a Model IDs filter, check the exact ID against the catalog for this key. An allowlist narrows discovery; it does not grant access to a model.

### 404 or connection check fails

Use https://api.lumaos.cloud/v1 as the connection URL, without /chat/completions. The app adds the API path. Check connectivity from the Open WebUI server or container, which may have different network access from your browser.

### Chat works, but titles, search or uploads fail

Check the model selected for background tasks. Turn off the failing extra feature and repeat a plain text chat. A chat connection does not configure an embedding model, document retrieval or an image-generation service.

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

- [Open WebUI: OpenAI-compatible connections](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)

---

# AnythingLLM + Luma Cloud

Use Luma Cloud as the language model for your workspace.

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.

- AnythingLLM Desktop, or administrator access to your AnythingLLM installation. Have the selected model's context and output limits available.

## Setup

1. **Open the language-model settings**
   Open Settings → AI Providers → LLM and choose Generic OpenAI. During first-time setup, this selection appears under LLM Preference. These settings establish the system default for workspaces without an override.

2. **Enter your connection**
   Set Base URL to https://api.lumaos.cloud/v1 and paste your Luma key into API Key. In Selected Model, choose the catalog ID you copied. If discovery is unavailable and the field permits manual input, enter that ID directly.

3. **Set the token limits**
   Model context window is the total space available to the conversation. Max Tokens is the output budget for a reply. Use the selected model's published limits and keep Max Tokens within its output limit; do not reuse another model's values.

4. **Save and check the workspace**
   Click Save changes. Open the intended workspace's settings → Chat Settings and check Workspace LLM Provider and Workspace Chat model. An existing workspace override takes precedence over the system default.

5. **Try a plain conversation**
   Use Chat mode for the first test, open a fresh conversation in that workspace, and send “Reply with hello.” Agent Configuration is separate; configure it later if you need agent tools.

## Connection fields

- LLM Provider: Generic OpenAI

- Base URL: https://api.lumaos.cloud/v1

- API Key: Your Luma Cloud API key

- Selected Model: MODEL_ID_FROM_CATALOG

- Model context window: The selected model's published context limit

- Max Tokens: An output budget within that model's limit

## Verify

- Wait for the workspace to show a completed text answer. Query mode can require document context, so use Chat for this test.

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

- If the selected model is wrong, inspect Workspace Chat model and the separate Agent Configuration before changing your Luma key.

## Limits

- Configure document embeddings separately. Selecting this chat provider does not make Luma Cloud an embedding service.

- Agent tools depend on the model and your AnythingLLM version. Check a simple tool action before relying on an unattended workflow.

- A shared installation's system model may serve several workspaces. Use a key intended for that installation and check workspace access before adding personal credentials.

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

### The workspace still answers with another model

Open that workspace's Chat Settings. Its provider and model can override the system default. For @agent conversations, inspect Agent Configuration separately, then start a fresh conversation.

### Selected Model is empty

Recheck Base URL https://api.lumaos.cloud/v1 and the key. Current Generic OpenAI settings offer manual model entry when discovery returns no models. Enter an exact available catalog ID; do not use a display name or keep the placeholder.

### Documents cannot be embedded or Query returns no answer

Test Chat mode without documents first. Configure the embedding provider separately and finish document processing before Query mode. A successful LLM reply does not test document indexing.

### Context or output limit error

Use the selected model's limits for Model context window and Max Tokens. Start a new short conversation and reduce retrieved document context. Increasing the local setting cannot increase the model's real limit.

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

- [AnythingLLM: OpenAI Generic](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic)

- [AnythingLLM: system, workspace and agent models](https://docs.anythingllm.com/setup/llm-configuration/overview)

- [AnythingLLM: provider settings source](https://github.com/Mintplex-Labs/anything-llm/blob/master/frontend/src/components/LLMSelection/GenericOpenAiOptions/index.jsx)

- [AnythingLLM: settings navigation](https://github.com/Mintplex-Labs/anything-llm/blob/master/frontend/src/components/SettingsSidebar/index.jsx)

- [AnythingLLM: interface labels and chat modes](https://github.com/Mintplex-Labs/anything-llm/blob/master/frontend/src/locales/en/common.js)

---

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

---

# Cherry Studio + Luma Cloud

Keep Luma Cloud in its own provider entry and choose its models in chat.

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.

- Cherry Studio with custom OpenAI providers.

## Setup

1. **Create a separate provider**
   Open Settings → Model Services → Add. Enter Luma Cloud as the name, select OpenAI as the provider type, and confirm Add. Keep any existing OpenAI provider entry.

2. **Fill in the connection**
   Select the new provider and enter your Luma key in API Key. Set API Address to https://api.lumaos.cloud/v1. Current versions recognize the existing /v1; a final slash is optional. If your version shows endpoint controls, select OpenAI Chat Completions for this guide and check that the URL preview ends in /v1/chat/completions.

3. **Add the models you want**
   Click Manage to fetch the model list, then click + beside a model to add it. For manual entry, use Add and enter the exact catalog ID as Model ID.

4. **Enable and select**
   Enable the provider switch. Return to chat, open a new conversation, and select the model under Luma Cloud in the model picker.

5. **Send a first message**
   Send “Reply with hello.” Use a text message without attachments for the first test.

## Connection fields

- Provider name: Luma Cloud

- Provider Type: OpenAI

- API Address: https://api.lumaos.cloud/v1

- API Key: Your Luma Cloud API key

- Model ID: MODEL_ID_FROM_CATALOG

- Provider switch: Enabled

## Verify

- Wait for a completed reply from the model selected under Luma Cloud.

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

- If the app returns 404, inspect the endpoint preview and confirm that the URL does not contain v1 twice. If the model is missing from chat, check that it was added in Manage and the provider is enabled.

## Limits

- Leave embeddings, image generation and speech on separately configured providers.

- Interface labels can vary by Cherry Studio version. The required values are the OpenAI provider type, API address, key and exact model ID.

- Keep the Luma Cloud credential inside its own provider entry. Changing an existing OpenAI entry would also change the connection used by its saved models.

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

### 404 or the address contains v1 twice

Set API Address to https://api.lumaos.cloud/v1 and inspect the request URL preview if your version shows one. Current versions normalize a final slash and preserve the existing /v1. Do not paste a full /chat/completions path into this field; use the Chat Completions endpoint choice when available.

### The provider is visible, but the model is not

Enable the provider, add the exact model ID to its model list, and choose it under Luma Cloud in a new chat. A display label is not the model ID; Manage and the chat selector are separate steps.

### The selected chat uses the wrong provider

Open the model selector in that conversation and choose the model under Luma Cloud. Existing conversations or assistants can retain their previous selection even after you add a new provider.

### A file, tool or image request fails

Return to a plain text message. Enable extra features only when both the selected model and the Luma API support that operation. The OpenAI provider type alone does not imply every OpenAI feature is available.

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

- [Cherry Studio: custom provider](https://docs.cherry-ai.com/cherry-studio-wen-dang/en-us/pre-basic/providers/zi-ding-yi-fu-wu-shang)

- [Cherry Studio: current API address handling](https://github.com/CherryHQ/cherry-studio/blob/main/src/shared/utils/api/format.ts)

- [Cherry Studio: endpoint URL previews](https://github.com/CherryHQ/cherry-studio/blob/main/src/renderer/pages/settings/ProviderSettings/hooks/providerSetting/buildHostEndpointPreviews.ts)

---

# n8n + Luma Cloud

Add Luma Cloud text generation to a workflow with an OpenAI Chat Model node.

API connection: Check client requirements. 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.

- An n8n version whose OpenAI credential exposes Base URL, with permission to create a workflow and credentials.

## Setup

1. **Build a small manual workflow**
   Create a workflow with Manual Trigger connected to Basic LLM Chain. Add OpenAI Chat Model to the chain's Model connector.

2. **Create a separate credential**
   In the model node, create an OpenAI credential named Luma Cloud. Enter your Luma key, set Base URL to https://api.lumaos.cloud/v1, leave Organization ID blank, and save.

3. **Select the model**
   Choose the Luma Cloud credential and the exact model ID from your catalog. If your version offers manual model entry, use it when discovery cannot select that ID. Keep Use Responses API off for this guide.

4. **Enter a fixed prompt**
   In Basic LLM Chain, set Prompt to Define below. Set Prompt (User Message) to “Reply with hello.” Leave Require Specific Output Format off for this first text reply.

5. **Run and inspect the result**
   Click Execute Workflow and inspect the Basic LLM Chain output. Keep this test manual; configure bounded retries and review usage before adding a schedule.

6. **Use HTTP Request if the model node is incompatible**
   Create Manual Trigger → HTTP Request. Set Method to POST, URL to https://api.lumaos.cloud/v1/chat/completions, Authentication to Generic Credential Type → Header Auth, then save a credential with Name Authorization and Value Bearer followed by your Luma key. Turn on Send Body, choose JSON → Using JSON and paste the body below. Keep the secret in the credential, not in the node body.

## Connection fields

- Credential type: OpenAI

- Base URL: https://api.lumaos.cloud/v1

- API Key: Your Luma Cloud API key

- Organization ID: Leave blank

- Model: MODEL_ID_FROM_CATALOG

- Use Responses API: Off for this guide

- Chain: Prompt: Define below

- Chain: Prompt (User Message): Reply with hello.

- Require Specific Output Format: Off for the first test

## HTTP Request fallback: JSON body

```json
{
  "model": "MODEL_ID_FROM_CATALOG",
  "messages": [
    {
      "role": "user",
      "content": "Reply with hello."
    }
  ],
  "stream": false
}
```

Paste this into the HTTP Request node's JSON body after replacing the model placeholder. Authentication stays in the Header Auth credential. This is a request body, not an importable workflow.

## Read the HTTP reply in the next node

```text
{{ $json.choices[0].message.content }}
```

Use this expression after a successful non-streaming HTTP Request with its default response-body output. If Include Response Headers and Status is enabled, the reply is under $json.body instead.

## Verify

- One workflow item should produce a completed text answer in the chain output. A credential connection check alone does not test a prompt, model or tool.

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

- If the chain asks for chatInput, change Prompt to Define below or provide that field from the previous node. For the example above, Define below avoids needing an input field.

## Limits

- Use this guide for the OpenAI Chat Model node. Other OpenAI operations, embeddings, uploaded files and hosted tools may require API features this connection does not provide.

- If your version cannot override Base URL or select the returned model, use an HTTP Request node with the request shown in the API quickstart instead.

- Workflow retries and background runs can spend additional credit. Avoid unlimited retries, especially after an uncertain network result.

- Keep custom sampling parameters unset for the first test. Built-in tools and structured output require compatible model features and separate verification.

- Model sub-nodes resolve expressions against the first input item. For batches needing different models or prompts, verify item handling explicitly before enabling production runs.

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

### The chain asks for chatInput

For the manual test, choose Define below in the chain's Prompt field and enter the fixed message. Connected Chat Trigger mode expects its own input field; it is a different workflow.

### The model cannot be selected or the node calls the wrong endpoint

Select the separate Luma Cloud credential and confirm its Base URL. Keep Use Responses API off. If the node still cannot use your model ID, use the HTTP Request fallback with the explicit URL and body above.

### A request succeeds but the next node gets no text

Inspect the actual output. The Basic LLM Chain and HTTP Request nodes return different shapes. For the non-streaming HTTP example, use choices[0].message.content; include body first only when the full response option is enabled.

### The workflow repeatedly retries or spends more than expected

Stop the schedule and inspect execution history, retry settings and item count. An agent can make several model calls for one user request. Test with one input and a small retry limit before restoring automation.

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

- [n8n: OpenAI Chat Model](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.lmchatopenai/)

- [n8n: OpenAI credential fields](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/credentials/OpenAiApi.credentials.ts)

- [n8n: Basic LLM Chain prompt settings](https://docs.n8n.io/integrations/builtin/cluster-nodes/root-nodes/n8n-nodes-langchain.chainllm/)

- [n8n: Manual Trigger](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger/)

- [n8n: HTTP Request](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/)

- [n8n: HTTP Request credentials](https://docs.n8n.io/integrations/builtin/credentials/httprequest/)

---

# Dify + Luma Cloud

Configure a Luma Cloud chat model for a Dify app or workflow.

API connection: Check client requirements. 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.

- Workspace owner or administrator access in Dify. Have the selected model's context and output limits available.

## Setup

1. **Install the model provider**
   Open Integrations → Model Provider and install the official OpenAI-API-compatible provider. In older layouts, Model Provider is under workspace Settings. Choose the model provider, not the similarly named extension that publishes Dify apps as an API.

2. **Add the model**
   Open the provider card and use Setup or Add Model. Choose model type LLM. Enter the exact catalog ID as Model Name; use a friendly Model display name such as Luma Cloud if desired. The display name does not change the ID sent to the API.

3. **Set the connection and protocol**
   Enter https://api.lumaos.cloud/v1 as API Base URL and your Luma key as API Key. Keep Completion mode at Chat. If the plugin exposes API Type, select Chat Completions API. If it exposes model name for API endpoint, leave it empty to use Model Name, or enter the same exact catalog ID.

4. **Set only the capabilities you need**
   Enter the selected model's published context size and an output limit within its allowance. Begin with text, without vision, tools, structured output or provider-specific extra settings. Leave optional sampling overrides unset where possible. Save the model; plugin validation can make a model request.

5. **Create a small app test**
   In your app, select this model in the LLM node. Set a fixed User message: Reply with hello. Run the node's preview first; if using a Chatflow, connect its text output to an Answer node so the reply reaches chat. Keep the test unpublished until it works.

6. **Add the rest of the workflow**
   After text succeeds, add one tool or retrieval step at a time. Use a separate embedding provider for knowledge indexing. Review retry and loop limits before sharing or scheduling an app.

## Connection fields

- Provider plugin: OpenAI-API-compatible

- Model type: LLM

- Model Name: MODEL_ID_FROM_CATALOG

- API Base URL: https://api.lumaos.cloud/v1

- API Key: Your Luma Cloud API key

- Completion mode: Chat

- API Type, when present: Chat Completions API

- Model context size: The selected model's published context limit

## LLM node: first User message

```text
Reply with hello.
```

A fixed prompt makes the first run independent of workflow variables, knowledge retrieval or tool configuration. Add dynamic inputs after this succeeds.

## Verify

- Preview the LLM node and check for completed text output, not only a saved provider card.

- In a Chatflow, confirm that the Answer node displays the LLM output to the user.

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

## Limits

- Providers and their credentials are shared across a Dify workspace. Requests made with this key use its Luma Cloud balance or quota, including other workspace members' app runs.

- The provider plugin supports several model types, but selecting it does not mean Luma Cloud supplies embeddings, reranking, speech or every optional API operation. This guide configures text generation only.

- Agent tools require a model that supports the required tool-call format. A feature toggle cannot add a missing model capability. Test tools separately from chat before publishing an agent.

- Field names and available protocol controls depend on the installed provider plugin version. If the plugin sends an unsupported parameter that it cannot disable, use the API quickstart or another compatible client.

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

### The model is absent from the app picker

Confirm that the model was saved as type LLM in the correct workspace and passed the provider's setup check. Select that provider/model explicitly in each LLM node; existing nodes do not automatically switch.

### Model not found, 404 or validation fails

Use https://api.lumaos.cloud/v1 as API Base URL and the exact catalog ID as Model Name. If an endpoint model-name override is set, check it too. Use Chat Completions and Chat mode for this guide; do not append /chat/completions to the base URL.

### Unsupported parameter or token-limit error

Remove optional extra settings and sampling overrides. Check context size and output budget against the chosen model. If the error names the output-token field and your plugin exposes Token parameter name, select the field required by the model's API contract; do not increase limits at random.

### The node succeeds, but chat is blank or knowledge fails

Connect the LLM text output to the Chatflow Answer node. For knowledge errors, check the separate embedding/retrieval configuration. Neither issue is fixed by replacing a working chat API key.

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

- [Dify: model providers and credentials](https://docs.dify.ai/en/cloud/use-dify/workspace/model-providers)

- [Dify: official OpenAI-compatible provider fields](https://github.com/langgenius/dify-official-plugins/blob/main/models/openai_api_compatible/provider/openai_api_compatible.yaml)

- [Dify: LLM node and output](https://docs.dify.ai/en/cloud/use-dify/nodes/llm)

---

# Flowise + Luma Cloud

Use a custom OpenAI-compatible chat model in a Flowise Chatflow.

API connection: Check client requirements. 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.

- Access to a trusted Flowise installation with a custom OpenAI chat-model node. Use a model compatible with the parameters that your node sends.

## Setup

1. **Create a test Chatflow**
   Open Chatflows and create a new flow. Add Chains → LLM Chain, Prompts → Prompt Template and Chat Models → OpenAI Custom Model. Some versions call the last node ChatOpenAI Custom. Use the custom node when the standard ChatOpenAI dropdown cannot select your exact model ID.

2. **Create a Luma credential**
   In the model node's Connect Credential field, choose Create New. Give the credential a recognizable name such as Luma Cloud and put your Luma key in OpenAI API Key. Select this saved credential on the node; do not put the key in the prompt or Base Options.

3. **Configure the model**
   Enter the catalog ID in Model Name. Open Additional Parameters and set Base Path to https://api.lumaos.cloud/v1. Leave Base Options blank unless you need a documented custom header. Set output limits only within the selected model's allowance.

4. **Check parameter compatibility**
   Inspect Temperature and other parameters the node supplies by default. Use values accepted by the selected model. Some node versions always send Temperature; if your model rejects it and the node cannot omit it, use another compatible client instead of repeatedly retrying the same flow.

5. **Connect the prompt and model**
   Set the Prompt Template to Question: {question}. Connect the custom model output to the LLM Chain's Language Model input, and the template output to its Prompt input. Save the Chatflow before testing.

6. **Run one text request**
   Open the flow's chat preview and send Reply with hello. Start without tools, memory, file uploads or retrieval. After a completed answer, add those features individually and check the extra model calls they create.

## Connection fields

- Node: OpenAI Custom Model / ChatOpenAI Custom

- Credential: A separate Luma Cloud OpenAI API credential

- Model Name: MODEL_ID_FROM_CATALOG

- Additional Parameters → Base Path: https://api.lumaos.cloud/v1

- Base Options: Leave blank

- Temperature: A value accepted by the chosen model; see compatibility step

- Prompt Template: Question: {question}

## Prompt Template

```text
Question: {question}
Answer clearly and briefly.
```

Enter this into the Prompt Template node. The chat question fills {question}. This is prompt content, not a Flowise import file or a place for credentials.

## Verify

- Save the flow and wait for a completed reply in its chat preview.

- Confirm the Luma credential and exact Model Name are selected on the node used by this flow.

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

## Limits

- This guide covers Chat Completions in Chatflows. It does not configure OpenAI Assistants, hosted tools, image generation or embeddings.

- An agent node may send tool schemas and several follow-up requests. Tool calling needs separate verification with the chosen model; a successful LLM Chain test is not an agent test.

- Anyone who can run a shared flow may consume its credential's balance or quota. Configure access to your Flowise app before sharing its chat or prediction endpoint.

- The custom model node's exact parameters vary by release. A model that rejects an unconfigurable default parameter needs a different compatible node/client; do not patch application files to bypass the error.

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

### The model is missing from the dropdown

Use OpenAI Custom Model / ChatOpenAI Custom and enter the exact catalog ID in Model Name. A predefined model dropdown is not a complete list of models your Luma key can use.

### 404 or requests go to the default OpenAI address

Check Additional Parameters → Base Path on the model node connected to this flow. It must be https://api.lumaos.cloud/v1, without /chat/completions. Save the flow and verify that an older model node is not still connected.

### Missing prompt variable or no output

Use {question} in the Prompt Template and connect that template to the LLM Chain. Check both graph connections and save before opening chat preview. Start without an output parser or a retrieval chain.

### Temperature or another parameter is rejected

Read the named field in the error. Remove optional overrides when the node permits it. If the node always sends a parameter your model rejects, stop here and use a compatible client or the API quickstart; changing the key will not fix the request format.

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

- [Flowise: custom OpenAI base URL and model](https://docs.flowiseai.com/integrations/langchain/chat-models/azure-chatopenai)

- [Flowise: custom model node fields](https://github.com/FlowiseAI/Flowise/blob/main/packages/components/nodes/chatmodels/ChatOpenAICustom/ChatOpenAICustom.ts)

- [Flowise: connecting a model and prompt to LLM Chain](https://docs.flowiseai.com/integrations/langchain/chat-models/chathuggingface)

---

# Any OpenAI-compatible client + Luma Cloud

Connect another editor, agent or app that accepts a custom OpenAI API URL and key.

API connection: Check client requirements. 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

- A client with a documented custom Base URL, API-key field and model selector. A model selector alone is not sufficient.

- A Luma Cloud API key from Dashboard → API, with Wallet funds or an eligible subscription key. SuperGPT desktop sign-in is separate.

- An exact model ID from GET /models using that key, and a client protocol matching Chat Completions or Responses.

## Setup

1. **Check the client's provider options**
   Open Settings → Models, Providers or Connections. Look for OpenAI Compatible, Custom OpenAI or a configurable OpenAI endpoint. If it only accepts a vendor login or an Anthropic/Gemini endpoint, use one of the supported clients in this directory instead; changing a URL cannot translate the protocol.

2. **Add a separate connection**
   Name it Luma Cloud. Keep existing providers and the current default until the new connection is verified. In a config file, merge only the new provider entry; do not replace the whole file. Use the client's own documentation for its schema and file location.

3. **Set the URL and credentials**
   Use https://api.lumaos.cloud/v1 for a Base URL field. Enter your key in the client's secure credential field. If it asks for a full Chat Completions endpoint instead, use https://api.lumaos.cloud/v1/chat/completions. A header-based connector needs Authorization: Bearer followed by the actual key and Content-Type: application/json.

4. **Choose the protocol and model**
   Start with Chat Completions unless the client specifically requires Responses. Paste an exact model ID returned for your key. Do not add an OpenAI or Luma prefix unless that client's guide explicitly requires one. Only enable tools, vision or other optional features after checking both model and client support.

5. **Save and select the connection**
   Reload the client if its documentation requires it. Select Luma Cloud and the intended model in the chat or agent itself; saving a provider does not always select it. A GUI app opened from the Dock or Start menu may not inherit variables set in a terminal.

## Connection fields

- Provider: OpenAI Compatible / Custom OpenAI

- Base URL: https://api.lumaos.cloud/v1

- API key: Your key from Dashboard → API, stored in the client's secure field

- Model ID: MODEL_ID_FROM_CATALOG

## macOS / Linux: private terminal variables

```sh
# macOS / Linux: enter the key when prompted, not in the command itself.
read -r -s LUMA_CLOUD_API_KEY
export LUMA_CLOUD_API_KEY
export LUMA_CLOUD_BASE_URL="https://api.lumaos.cloud/v1"
# Replace the value below with an ID returned for your key.
export LUMA_CLOUD_MODEL="MODEL_ID_FROM_CATALOG"
```

Enter the key at the hidden prompt. Replace the model placeholder after listing available models. These variables only last in this terminal session.

## List models for your key

```sh
curl --fail-with-body "https://api.lumaos.cloud/v1/models" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY"
```



## Check Chat Completions

```sh
curl --fail-with-body -N "https://api.lumaos.cloud/v1/chat/completions" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "messages": [{"role": "user", "content": "Reply with hello."}],
  "stream": true
}
JSON
```

Run after setting a returned model ID. This request uses funds or quota.

## Windows PowerShell 7: private terminal variables

```powershell
$env:LUMA_CLOUD_API_KEY = Read-Host "Luma Cloud API key" -MaskInput
$env:LUMA_CLOUD_BASE_URL = "https://api.lumaos.cloud/v1"
$env:LUMA_CLOUD_MODEL = "MODEL_ID_FROM_CATALOG"
```



## Windows: list models and make a short request

```powershell
$headers = @{ Authorization = "Bearer $env:LUMA_CLOUD_API_KEY" }
$models = Invoke-RestMethod "$env:LUMA_CLOUD_BASE_URL/models" -Headers $headers
$models.data | Select-Object id

$env:LUMA_CLOUD_MODEL = Read-Host "Model ID from the list above"
$body = @{
  model = $env:LUMA_CLOUD_MODEL
  messages = @(@{ role = "user"; content = "Reply with hello." })
  stream = $false
} | ConvertTo-Json -Depth 5
$result = Invoke-RestMethod "$env:LUMA_CLOUD_BASE_URL/chat/completions" -Method Post -Headers $headers -ContentType "application/json" -Body $body
$result.choices[0].message.content
```

Run the model-list part first, set the selected ID, then run the request part. The request uses funds or quota.

## Responses, when required by your client

```sh
curl --fail-with-body -N "https://api.lumaos.cloud/v1/responses" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "input": "Reply with hello.",
  "stream": true
}
JSON
```

Use a model that supports this protocol. This is an alternative request, not an extra required setup step.

## Verify

- List models with the intended key. This confirms catalog access, not a completed model response.

- Send a short message in the client and wait for the complete response. Check Usage → API Wallet for a Wallet key, or subscription Usage for a subscription key.

- For agent tools, ask the client to list files in a disposable folder without editing or running commands. Confirm that a real tool result returns before enabling broader actions.

## Limits

- Custom API support is a client feature; not every IDE, agent mode or cloud task accepts a third-party provider.

- Chat compatibility does not promise autocomplete, embeddings, image generation, audio, hosted assistants or every agent tool.

- A universal config file would not work across different clients. Use the exact per-client guide when available.

## Troubleshooting

### No custom URL field

Check the guide for your exact app and version. A compatible extension may work even when the IDE's built-in assistant cannot. Do not put a Luma key into an unrelated vendor login field.

### 401 or missing key

Confirm the actual API key is stored in the client. A literal LUMA_CLOUD_API_KEY or ${...} string only resolves where documented. Re-enter the key privately and restart the client if its secret store requires it.

### 404, unknown model or wrong endpoint

Check for duplicated /v1 or /chat/completions in the resulting URL, choose the correct protocol and copy an exact ID from your key's model list.

### 402 or 429

Check the key type, Wallet balance and relevant subscription allowance. For 429 follow Retry-After when present and lower parallel requests; do not repeatedly resend the same request in a tight loop.

### Chat works but tools fail

Check that the client sends tool definitions and that the selected model supports them. Start with one read-only tool. Autocomplete, embeddings and vision may use separate models and credentials.

### Terminal works, GUI does not

Use the app's credential field or documented secret file. Restart the app after configuration changes and check which connection is selected in the current conversation.

## Official client documentation

- [Continue: OpenAI-compatible configuration](https://docs.continue.dev/customize/model-providers/top-level/openai)

- [OpenCode: custom providers](https://opencode.ai/docs/providers/)