# Aider + Luma Cloud

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

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.

- Aider installed; open a small project you are comfortable testing. Run aider --version and check aider --help for the installed options.

## Setup

1. **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.

2. **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.

3. **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.

4. **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

```bash
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

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

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

```yaml
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

```bash
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

```powershell
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

```text
/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.

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

## Limits

- 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

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

## Official client documentation

- [Aider: OpenAI-compatible APIs](https://aider.chat/docs/llms/openai-compat.html)

- [Aider: model and configuration options](https://aider.chat/docs/config/options.html)

- [Aider: ask and editing modes](https://aider.chat/docs/usage/modes.html)

- [Aider: separate YAML configuration files](https://aider.chat/docs/config/aider_conf.html)

- [Aider: read-only files and chat commands](https://aider.chat/docs/usage/commands.html)