You are on the Custom provider screen. Fill it in like this.
The simplest path uses the Custom provider form: paste the Base URL and your one-time API key, save, then choose an id returned by the authenticated model catalog.
OpenCode provider form
Provider ID
luma-cloud
The first field in your window. Lowercase only; hyphens are allowed.
Display name
Luma Cloud
The second field. This is how the provider will appear in the list.
Base URL
https://api.lumaos.cloud/v1
The third field. Take it from Luma Cloud -> App -> API. It usually ends with /v1.
API key
API key created in App → API
The fourth field. Paste the one-time secret you copied when creating the key.
Model after saving
gpt-5.5
Selected in the bottom model picker, not in this modal.
Custom provider screen
Here is what goes into the fields on your screen.
If you see the Provider ID, Display name, Base URL, and API key fields, this is the right window. The values below are in the same order.
OpenCode screen: Custom provider
Go top to bottom and paste exactly these values.
Provider ID
placeholder: myprovider
luma-cloud
This is the technical name. OpenCode prefixes live model ids with luma-cloud/.
Display name
placeholder: My AI Provider
Luma Cloud
This is the friendly name shown in the UI. Copy it exactly as is.
Base URL
placeholder: https://api.myprovider.com/v1
https://api.lumaos.cloud/v1
This is the endpoint from the dashboard. Do not add /chat/completions to this field.
API key
placeholder: API key
API key created in App → API
This is a secret key. It goes here, not into JSON and not into the chat.
After that
Click the bottom button of the form: Save, Connect, Add provider, or Continue. Then choose an exact model currently advertised for this key.
Quick cheat sheet
You can literally copy it line by line.
Provider ID
luma-cloud
Display name
Luma Cloud
Base URL
https://api.lumaos.cloud/v1
API key
API key created in App → API
Model picker
gpt-5.5
How OpenCode may display the selected model
luma-cloud/gpt-5.5
What not to pick manually as the model id
GPT-5.5X High, 5.5x high, x GPT-5.5
Rules
What not to show a regular user.
OpenCode should only see the public Luma Cloud endpoint, the API key you explicitly created, and the canonical model id. Internal topology stays inside the product.
Do not enter the bridge endpoint
No 127.0.0.1:20333, shard URLs, or LumaCloud bridge host for an external client.
Do not use a display label as the model id
GPT-5.5X High is fine to show in the UI, but the copy-safe id for OpenCode is gpt-5.5-xhigh.
Do not mix SuperCodex and OpenCode
SuperCodex manages its product connection separately. Regular OpenCode uses the customer-created API key and Custom provider.
Use the dashboard endpoint
If the dashboard shows a different Base URL, use that one. This page shows the current runtime default.
OmniRoute pattern
How to make it as smooth as OmniRoute.
The same simplicity principle applies here: one key, one Base URL, and authenticated model discovery. Luma Cloud never fills missing efforts from a static list.
How OmniRoute works
In Codex, the OmniRoute provider is pre-baked into a dedicated app/launcher profile: provider id, base URL, wire API, env key, default model, and reasoning. The user never assembles this by hand.
The OpenCode equivalent
For OpenCode, the equivalent is a small provider.luma-cloud config with the public endpoint, safe limits, and an environment-variable key reference. Authenticated GET /v1/models remains the only model authority.
What a regular user sees
The UI keeps the actions simple: create a key once, copy the Base URL, and fill the Custom provider form. The optional skeleton contains only public settings and an environment-variable reference.
Covered today, no magic
This page offers a field-by-field Custom provider walkthrough and a downloadable secret-free provider skeleton as an optional project-level fallback.
The next product level
Register Luma Cloud as a known provider in OpenCode/models.dev so /connect works like OpenRouter, without the local profile fallback.
Auto-discovery like OpenAI
Full auto-discovery requires becoming a known provider in the OpenCode catalog/models.dev, or waiting for (or contributing) remote provider manifest support for custom providers.
Path
A step-by-step, mouse-only path through OpenCode.
Wording varies between builds: Providers, Connect provider, Add provider. But if a Custom provider form with four fields opens, that is the one.
Create the API key in Luma Cloud
Open Luma Cloud → App → API. Add prepaid credit when needed, create a named key, and copy the secret when it is shown once.
Screen
Luma Cloud -> App -> API
Action
Create API key, Copy secret
Open the Custom provider form
In OpenCode, click the gear icon in the bottom left, open Providers, and choose Add provider / Connect provider / Custom provider. If you already see the Custom provider window, you are in the right place.
Screen
Settings -> Providers
Action
Add custom provider
Fill in the fields in the modal
Provider ID: luma-cloud. Display name: Luma Cloud. Base URL: the value from the dashboard. API key: the secret you explicitly created. No shard URLs, bridge URLs, or 127.0.0.1:20333.
Screen
Custom provider
Action
Fill Provider ID, Display name, Base URL, API key
Save the provider
Click the bottom button of the form: Save, Connect, Add provider, or Continue. The label depends on your OpenCode version, but the meaning is the same: save this custom provider.
Screen
Provider form
Action
Save / Connect
Pick the model in OpenCode
At the bottom of the OpenCode window, click the current model, then choose an exact Luma Cloud id returned by the authenticated live catalog. Start with gpt-5.5 when it is advertised; its default effort is medium.
Screen
Bottom model picker
Action
Luma Cloud -> an advertised exact id
Send a quick test
Write a small prompt, for example: Reply in one sentence that Luma Cloud is connected. If a reply comes back, the setup is done.
Screen
New chat
Action
Send test prompt
OpenCode profile
Download a secret-free OpenCode provider skeleton.
Create an API key in App → API first. The skeleton contains the public endpoint and references LUMA_CLOUD_API_KEY; it contains no secret or static model list.
Set the key on macOS or Linux
Replace lc_live_... with the one-time secret you saved. This applies to the current terminal session.
export LUMA_CLOUD_API_KEY="lc_live_..."Set the key in Windows PowerShell
Replace lc_live_... with the one-time secret you saved. This applies to the current PowerShell session.
$env:LUMA_CLOUD_API_KEY="lc_live_..."Fetch the current model ids
This Node command works in both shells. Use only ids returned by the authenticated catalog; do not copy the whole candidate table.
node -e "fetch('https://api.lumaos.cloud/v1/models',{headers:{Authorization:'Bearer '+process.env.LUMA_CLOUD_API_KEY}}).then(r=>r.json()).then(x=>console.log(x.data.map(m=>m.id).join('\n')))"Copy provider skeleton
A public example with an environment-variable reference. Downloaded profiles never include an internal product credential or raw API secret.
{
"$schema": "https://opencode.ai/config.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}",
"timeout": 600000,
"chunkTimeout": 300000
}
}
}
}For a single project
opencode.json in the project root
For all projects
~/.config/opencode/opencode.json
The key stays in an environment variable
LUMA_CLOUD_API_KEY
What exactly to do with the config
The skeleton does not go into the chat or the API key field. It is an opencode.json file that gives OpenCode the provider, endpoint, and safe limits without claiming that any model is available.
Open Luma Cloud App → API, create a key, and save its one-time secret in LUMA_CLOUD_API_KEY.
Download the secret-free OpenCode provider skeleton after the dashboard confirms that an active API key exists.
Place the skeleton in the project root or merge provider.luma-cloud into ~/.config/opencode/opencode.json. It intentionally contains no model entries.
Fetch GET /v1/models with your key and add only the exact returned ids to provider.luma-cloud.models if your OpenCode build requires configured models in its picker.
Important
If the user already has ~/.config/opencode/opencode.json, do not silently replace the file. Merge provider.luma-cloud into the existing config or use a project-level opencode.json.
Auto models
Why you cannot just type X-X and expect auto-discovery.
This is an important product difference: a Base URL and API key alone do not mean OpenCode knows the full model lineup and capabilities.
Why OpenAI looks automatic
OpenCode knows standard provider ids and their models from its provider catalog/models.dev. That is why with OpenAI it often looks like the models appeared on their own right after the key.
What happens with a custom provider
For an arbitrary Provider ID like luma-cloud, OpenCode does not know the model list in advance. The reliable way to populate the picker is provider.models in the OpenCode config. A wildcard like X-X will not load the model list on its own.
What Luma Cloud already does
Our endpoint serves authenticated GET /v1/models with the same bearer key. The secret-free skeleton intentionally contains no static model claims; use only ids returned for your key.
Models
Maximum candidate ids; your live list may be smaller.
Only exact lowercase dashed ids returned by authenticated GET /v1/models are accepted. A candidate that fails fleet verification is omitted individually.
Fetch your live verified subset
The candidate table below documents possible ids. This command returns the only ids currently valid for your credential.
node -e "fetch('https://api.lumaos.cloud/v1/models',{headers:{Authorization:'Bearer '+process.env.LUMA_CLOUD_API_KEY}}).then(r=>r.json()).then(x=>console.log(x.data.map(m=>m.id).join('\n')))"How to read the names
`gpt-5.5` is the family id with medium as its default effort. `gpt-5.5-xhigh`, `gpt-5.5-high`, `gpt-5.5-medium`, and `gpt-5.5-low` are explicit reasoning presets. OpenCode model ids are always written exactly as the Gateway catalog returns them.
gpt-5.5
GPT-5.5
gpt-5.5-low
GPT-5.5 Low
gpt-5.5-medium
GPT-5.5 Medium
gpt-5.5-high
GPT-5.5 High
gpt-5.5-xhigh
GPT-5.5 xHigh
gpt-5.6-sol
GPT-5.6 Sol
gpt-5.6-sol-low
GPT-5.6 Sol Low
gpt-5.6-sol-medium
GPT-5.6 Sol Medium
gpt-5.6-sol-high
GPT-5.6 Sol High
gpt-5.6-sol-xhigh
GPT-5.6 Sol xHigh
gpt-5.6-sol-max
GPT-5.6 Sol Max
gpt-5.6-sol-ultra
GPT-5.6 Sol Ultra
gpt-5.6-terra
GPT-5.6 Terra
gpt-5.6-terra-low
GPT-5.6 Terra Low
gpt-5.6-terra-medium
GPT-5.6 Terra Medium
gpt-5.6-terra-high
GPT-5.6 Terra High
gpt-5.6-terra-xhigh
GPT-5.6 Terra xHigh
gpt-5.6-terra-max
GPT-5.6 Terra Max
gpt-5.6-terra-ultra
GPT-5.6 Terra Ultra
gpt-5.6-luna
GPT-5.6 Luna
gpt-5.6-luna-low
GPT-5.6 Luna Low
gpt-5.6-luna-medium
GPT-5.6 Luna Medium
gpt-5.6-luna-high
GPT-5.6 Luna High
gpt-5.6-luna-xhigh
GPT-5.6 Luna xHigh
gpt-5.6-luna-max
GPT-5.6 Luna Max
Modes
Where to configure by hand, and where everything is already baked in.
This deserves explicit highlighting in the UI so people do not assume SuperCodex and regular OpenCode are set up the same way.
If this is SuperCodex
SuperCodex manages its product connection separately. Direct API keys created in App → API are only for external tools such as regular OpenCode.
If this is regular OpenCode
The user adds Luma Cloud as a separate OpenAI-compatible provider and picks a model from the list below.
If your build has no full provider form
Some OpenCode versions save only the key via /connect. In that case, use the Custom provider block below or download the secret-free profile after creating a key.
Troubleshooting
If OpenCode complains.
Health check for the current endpoint: https://api.lumaos.cloud/healthz. If it does not open, fix the endpoint first, then OpenCode.
Request body does not match the supported local alpha contract
Check the provider type, the Base URL with /v1, and that the selected id is present in authenticated GET /v1/models. If an old opencode.json is in place, check limit.output: 128000, timeout: 600000, and chunkTimeout: 300000, otherwise OpenCode may cut off a long reasoning request.
OpenCode does not show Luma Cloud models
The Provider ID in the credentials and in the provider settings must match: luma-cloud. Then reopen the Model Picker or /models.
OpenCode opened empty after an old config
Rename ~/.config/opencode/opencode.json to opencode.broken-lumacloud.json and restart OpenCode. Then add only the provider.luma-cloud block shown below.
401 or invalid API key
Create or replace the API key in App → API and update LUMA_CLOUD_API_KEY. Do not use the endpoint as the key.
Quota or balance exhausted
The connection works, but the account has hit its limits. Open Billing or Analytics in Luma Cloud and check your current plan/quota.
Short version for support
Provider ID: luma-cloud. Display name: Luma Cloud. Type: OpenAI-compatible. Base URL: dashboard endpoint. API key: explicitly created in App → API. Model: an exact id from authenticated GET /v1/models.