API setup · Chat Completions

Aider + Luma Cloud

Connect Aider for a single terminal run using its OpenAI-compatible provider.

Connect with an API key

Use your Luma Cloud API key, Base URL and an available model ID with the client-specific settings below. SuperGPT desktop installation and sign-in are separate.

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.
Aider installed; open a small project you are comfortable testing. Run aider --version and check aider --help for the installed options.

Get an API key and a model ID →

Set up Aider

Choose the model
Copy an exact ID from Luma Cloud's model catalog and replace MODEL_ID_FROM_CATALOG below. Aider requires the openai/ prefix to select its compatible adapter; this prefix is not part of Luma's model ID.
Start a scoped run
Run the command from your project in Bash or Zsh. It starts in ask mode with automatic commits disabled. The environment and flags apply only to this run; saved provider defaults stay unchanged.
Check the first reply
Ask a short question in this initial session. Switch to an editing mode only when you want file changes; review the diff and run your checks before committing.
Save an optional reusable profile
For repeated use, save the YAML example as aider.luma.yml in your project and select it explicitly with --config. It contains no secret. This selects one config file instead of the normal home/project .aider.conf.yml chain, so copy any approval or workflow settings you still need into this separate profile deliberately. Keep the API key in your local environment.

Bash / Zsh — one Aider run

OPENAI_API_BASE="https://api.lumaos.cloud/v1" \
OPENAI_API_KEY="${LUMA_CLOUD_API_KEY:?Load LUMA_CLOUD_API_KEY from your secret store first}" \
aider --model openai/MODEL_ID_FROM_CATALOG --chat-mode ask --no-auto-commits --no-dirty-commits

The key comes from an existing environment variable. Do not paste the key value into the command.

macOS / Linux · Bash or Zsh · private key input

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

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

Optional aider.luma.yml · no API key in this file

model: openai/MODEL_ID_FROM_CATALOG
openai-api-base: https://api.lumaos.cloud/v1
chat-mode: ask
auto-commits: false
dirty-commits: false

Replace the model placeholder. On every OS, the relative path below means the directory where you start Aider. Name it aider.luma.yml so it is used only when you explicitly select it.

macOS / Linux · run with the separate profile

OPENAI_API_KEY="${LUMA_CLOUD_API_KEY:?Enter your Luma key first}" aider --config ./aider.luma.yml

This assigns OPENAI_API_KEY only to the Aider process. Your shell's existing OpenAI key stays unchanged.

Windows · PowerShell · run and restore the previous OpenAI environment

if (-not $env:LUMA_CLOUD_API_KEY) { throw 'Enter your Luma key first.' }
$lumaPreviousOpenAiKey = [Environment]::GetEnvironmentVariable('OPENAI_API_KEY', 'Process')
try {
  $env:OPENAI_API_KEY = $env:LUMA_CLOUD_API_KEY
  aider --config .\aider.luma.yml
} finally {
  [Environment]::SetEnvironmentVariable('OPENAI_API_KEY', $lumaPreviousOpenAiKey, 'Process')
  Remove-Variable lumaPreviousOpenAiKey
}

Save the YAML profile above first. This restores the previous variable after Aider exits, including an originally unset variable. The key never becomes a command-line argument.

Inside Aider · read one file without editing

/read-only README.md
Summarize the purpose of README.md. Do not edit files or run commands.

Use a harmless README in your test project. Aider's read-only file attachment is a client feature; this is not a claim that the model called a remote file tool.

Check the connection

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.

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

Aider may not recognize a custom model's context limit, pricing, or preferred edit format. Use the selected model's documented settings; do not invent token limits to hide a warning.
Chat compatibility does not guarantee that every model works equally well with Aider's editing workflow.

Troubleshooting Aider

Unknown provider or model

Aider needs openai/ before the exact Luma model ID to choose the compatible adapter. The API itself receives the ID without that prefix. Keep the same ID in the profile and command; use the authenticated Luma catalog to check it.

The request goes to the wrong API

Check the startup model and the selected --config file. For the one-run command, OPENAI_API_BASE must be Luma's Base URL. For the reusable profile, check openai-api-base. Review existing AIDER_* environment overrides locally without dumping secrets.

401 despite a working dashboard login

Aider needs a portable API key, not browser login or a desktop token. Enter it locally, then launch from that terminal. In PowerShell, use the try/finally example to avoid replacing your normal OpenAI variable permanently.

Context, price or edit-format warning

Unknown custom-model metadata does not automatically mean authentication failed. Use the chosen model's documented limits and Aider model settings when available. First verify a short ask-mode reply; only then try an edit on a disposable file and inspect its diff.

Client documentation

Settings checked on 2026-09-28. These instructions are based on the client’s documentation; installed versions may differ.

Open API Wallet & keys →Plain text for your agent