Codex CLI + 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.
• 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.
• Codex CLI with custom-provider and -c overrides. Check codex --help for your installed version.

Get an API key and a model ID →

Set up Codex CLI

1. Choose a Responses model

   Replace MODEL_ID_FROM_CATALOG with a Responses-capable Luma model and SUPPORTED_EFFORT_FROM_MODEL_DOCS with a reasoning effort that same model supports. The command selects provider, model, and effort together for this run, overriding any saved effort. Chat Completions alone is not enough for current Codex CLI.

2. Start a separate CLI session

   Use the command below from your project. Provider settings apply only to this invocation. Do not add them to ~/.codex/config.toml, overwrite your OpenAI provider, log out, or modify ChatGPT/Codex desktop.

3. Confirm the session

   Use /status and /debug-config to inspect the active session and configuration layers before the first request. Keep normal sandbox and approval controls enabled. When changing the model, also select an effort supported by the new model. Never use an existing OpenAI conversation as the first compatibility test.

4. Optional: save a CLI-only named profile

   Current Codex versions use a separate luma-cli.config.toml beside the user config, selected only with --profile luma-cli. The default location is ~/.codex/luma-cli.config.toml on macOS/Linux and %USERPROFILE%\.codex\luma-cli.config.toml on Windows. If you already use a custom Codex state location, keep it and use its documented profile directory. Create only this named file; do not edit the shared config.toml, auth.json or desktop settings. Codex versions before 0.134.0 use a different profile format: use the one-run command instead of copying this profile into an older format.

codex \
  --model 'MODEL_ID_FROM_CATALOG' \
  -c 'model_reasoning_effort="SUPPORTED_EFFORT_FROM_MODEL_DOCS"' \
  -c 'model_provider="luma_cloud"' \
  -c 'model_providers.luma_cloud.name="Luma Cloud"' \
  -c 'model_providers.luma_cloud.base_url="https://api.lumaos.cloud/v1"' \
  -c 'model_providers.luma_cloud.env_key="LUMA_CLOUD_API_KEY"' \
  -c 'model_providers.luma_cloud.wire_api="responses"' \
  -c 'model_providers.luma_cloud.requires_openai_auth=false' \
  -c 'model_providers.luma_cloud.supports_websockets=false'

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
}

model = "MODEL_ID_FROM_CATALOG"
model_provider = "luma_cloud"
model_reasoning_effort = "SUPPORTED_EFFORT_FROM_MODEL_DOCS"
web_search = "disabled"

[model_providers.luma_cloud]
name = "Luma Cloud"
base_url = "https://api.lumaos.cloud/v1"
env_key = "LUMA_CLOUD_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false

codex --version
codex --profile luma-cli --sandbox read-only

/status
/debug-config
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. Confirm a completed read-only file operation in the CLI, then its final answer. If only text succeeds, report chat verified and tools not yet verified. Do not enable web search, remote execution or automatic approvals as a connection workaround.

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

• Current official configuration documents wire_api=responses. Do not use older wire_api=chat examples.
• This setup documents the CLI connection, not desktop integration. Built-in web search, remote execution, images, and other optional features need separate support.

Troubleshooting Codex CLI