OpenCode + 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.
• 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.

Get an API key and a model ID →

Set up OpenCode

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.

Base URL

https://api.lumaos.cloud/v1

Provider ID

luma-cloud

Model selection

luma-cloud/MODEL_ID_FROM_CATALOG

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

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 --model luma-cloud/MODEL_ID_FROM_CATALOG

/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." 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.

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

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