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