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