OpenCode V2 + Luma Cloud

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.

Get an API key and a model ID →

Set up OpenCode V2

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.

{
  "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"
        }
      }
    }
  }
}

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

$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
}

opencode --version
opencode debug paths config
opencode --standalone

/models
Reply with: Luma connection ready.

Check the connection

1. Start a new session with the exact Luma Cloud model selected and ask for a short text reply. This is a billable API request.
2. 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.
3. 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.

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

What to expect

• 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 OpenCode V2