OpenCode setup

You are on the Custom provider screen. Fill it in like this.

No JSON, no terminal. You open Providers with the mouse, paste four values into the OpenCode form, save the provider, and pick a model in the bottom picker.

Open API and key What to enter in the form If models did not appear Model list

OpenCode provider form

preview

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

starter key from Luma Cloud

The fourth field. Click Copy starter key in the dashboard and paste it here.

Model after saving

gpt-5.5-xhigh

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. Later, OpenCode may display the model as luma-cloud/gpt-5.5-xhigh.

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

starter key from Luma Cloud

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 click the current model at the bottom of OpenCode and choose gpt-5.5-xhigh.

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

starter key from Luma Cloud

Model picker

gpt-5.5-xhigh

How OpenCode may display the selected model

luma-cloud/gpt-5.5-xhigh

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 starter key, 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 receives a ready-made profile. Regular OpenCode adds a Custom provider manually.

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.

OmniRoute never makes a person assemble the provider from pieces: the profile is prepared in advance. For OpenCode we build the same UX equivalent - a clear form plus a ready OpenCode profile with all models.

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 same product object is the Luma Cloud OpenCode profile: an opencode.json with provider.luma-cloud, the endpoint, all model ids, limits, and capabilities.

What a regular user sees

The UI keeps the actions simple: copy the installer, paste it into Terminal/PowerShell, pick Luma Cloud and a model. Nobody edits JSON by hand.

Covered today, no magic

This page offers a soft installer with backup, a field-by-field walkthrough of the modal, remote /.well-known/opencode, and a downloadable profile as a 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

Download OpenCode profile

Copy all model ids

If OpenCode asks you to list models manually, paste only these lowercase dashed ids.

gpt-5.5
gpt-5.5-xhigh
gpt-5.5-high
gpt-5.5-medium
gpt-5.5-low

Copy provider profile

A public example without the starter key. The personal profile from the dashboard can include the key so the user never edits JSON by hand.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "luma-cloud/gpt-5.5-xhigh",
  "provider": {
    "luma-cloud": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Luma Cloud",
      "options": {
        "baseURL": "https://api.lumaos.cloud/v1",
        "timeout": 600000,
        "chunkTimeout": 300000
      },
      "models": {
        "gpt-5.5": {
          "name": "GPT-5.5",
          "reasoning": true,
          "temperature": true,
          "tool_call": true,
          "attachment": false,
          "modalities": {
            "input": [
              "text"
            ],
            "output": [
              "text"
            ]
          },
          "limit": {
            "context": 400000,
            "output": 1024
          }
        },
        "gpt-5.5-xhigh": {
          "name": "GPT-5.5 xHigh",
          "reasoning": true,
          "temperature": true,
          "tool_call": true,
          "attachment": false,
          "modalities": {
            "input": [
              "text"
            ],
            "output": [
              "text"
            ]
          },
          "limit": {
            "context": 400000,
            "output": 1024
          }
        },
        "gpt-5.5-high": {
          "name": "GPT-5.5 High",
          "reasoning": true,
          "temperature": true,
          "tool_call": true,
          "attachment": false,
          "modalities": {
            "input": [
              "text"
            ],
            "output": [
              "text"
            ]
          },
          "limit": {
            "context": 400000,
            "output": 1024
          }
        },
        "gpt-5.5-medium": {
          "name": "GPT-5.5 Medium",
          "reasoning": false,
          "temperature": true,
          "tool_call": true,
          "attachment": false,
          "modalities": {
            "input": [
              "text"
            ],
            "output": [
              "text"
            ]
          },
          "limit": {
            "context": 400000,
            "output": 1024
          }
        },
        "gpt-5.5-low": {
          "name": "GPT-5.5 Low",
          "reasoning": false,
          "temperature": true,
          "tool_call": true,
          "attachment": false,
          "modalities": {
            "input": [
              "text"
            ],
            "output": [
              "text"
            ]
          },
          "limit": {
            "context": 400000,
            "output": 1024
          }
        }
      }
    }
  }
}

For a single project

opencode.json in the project root

Place the file next to package.json, .git, or the main project folder. Luma Cloud will only be available when OpenCode is open in this project.

For all projects

~/.config/opencode/opencode.json

A global user setting. After this, Luma Cloud appears in OpenCode in every project on this computer.

The key lives in the installer, not the public example

Dashboard installer / profile

The personal installer from the dashboard can write the starter key into your local OpenCode config. The public example on this page does not reveal the secret.

What exactly to do with the config

The profile does not go into the chat or the API key field. It is an opencode.json file that OpenCode reads the provider, endpoint, model list, and limits from.

The easiest path: open Luma Cloud App -> API and copy the OS-specific OpenCode installer.

On macOS/Linux, paste the installer into Terminal. On Windows, paste the Windows installer into PowerShell.

The installer makes a backup, merges only provider.luma-cloud into ~/.config/opencode/opencode.json, and does not touch your current model, sessions, or other providers.

Restart OpenCode and open the bottom model picker again. Choose Luma Cloud -> gpt-5.5-xhigh.

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 profile. A wildcard like X-X will not load the model list on its own.

What Luma Cloud already does

Our endpoint serves GET /v1/models with the same bearer key, and the public origin serves /.well-known/opencode for remote defaults. For the current custom provider flow, the installer remains a compatible fallback.

Models

Models you can choose.

In support and instructions we only use lowercase dashed ids. The gateway accepts aliases, but a regular user does not need them.

One list to copy

This is the entire current Luma Cloud model lineup for OpenCode. The default for a first connection is gpt-5.5-xhigh.

gpt-5.5
gpt-5.5-xhigh
gpt-5.5-high
gpt-5.5-medium
gpt-5.5-low

How to read the names

`gpt-5.5` is the short flagship alias. `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 lowercase with hyphens.

Do not type display labels like GPT-5.5X High into the model id field. The gateway may understand such aliases, but people and the OpenCode picker need the canonical id.

For complex tasks

gpt-5.5

GPT-5.5

Default GPT-5.5 route for deep Codex-style agent and reasoning work.

For complex tasks

default

gpt-5.5-xhigh

GPT-5.5 xHigh

Copy-safe flagship model id for the highest GPT-5.5 reasoning preset.

For complex tasks

gpt-5.5-high

GPT-5.5 High

Strong GPT-5.5 reasoning preset for complex work when xHigh is more than needed.

Balanced

gpt-5.5-medium

GPT-5.5 Medium

Balanced GPT-5.5 preset for everyday automation and mixed product traffic.

Fast

gpt-5.5-low

GPT-5.5 Low

Fast GPT-5.5 preset for previews, light tasks, and thin control loops.

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

Nothing needs to be added manually: the provider, endpoint, key, and model are already baked into the profile that Luma Cloud issues.

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, a regular user is better off taking the ready-made SuperCodex/OpenCode profile from Luma Cloud or asking support to enable a provider profile.

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 the gpt-5.5-xhigh model. If an old opencode.json is in place, check limit.output: 1024, 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 Windows installer

Rename ~/.config/opencode/opencode.json to opencode.broken-lumacloud.json and restart OpenCode. Then grab the fresh Windows soft installer: it makes a backup and merges only provider.luma-cloud.

401 or invalid API key

Copy a fresh starter key from the Luma Cloud dashboard and paste it into the OpenCode provider credentials. 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: starter key. Model: gpt-5.5-xhigh.

Back to docs