# Roo Code + Luma Cloud

Use the OpenAI Compatible provider with a model that supports native tool calling.

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 Luma Cloud API key in Dashboard → API and copy a model ID from the authenticated model catalog.

- Install Roo Code and choose a model with OpenAI-compatible native tool calling.

## Setup

1. **Open Roo's provider settings**
   Open the Roo Code sidebar and its settings gear. Select OpenAI Compatible as the API Provider. If you already use a profile, preserve it and configure Luma Cloud separately where your version supports profiles.

2. **Set URL, key, and model**
   Use https://api.lumaos.cloud/v1 as Base URL and the exact catalog model ID. Enter the key in Roo's API Key field on macOS, Windows, or Linux. Do not put the key in repository settings or add Authorization headers manually.

3. **Check model capabilities**
   Use a model with native tool calling. Set context and output limits from its details; do not guess them from the model name. Leave image/computer-use features off unless supported.

4. **Save the selection**
   Save, select the Luma Cloud configuration, and create a new task. Check the active model before sending. If the previous model remains selected, reopen Roo or reload the editor.

5. **Start a small task**
   Select the new configuration and ask Roo to read one harmless file. Review requested actions before allowing edits or commands.

## Connection fields

- Base URL: https://api.lumaos.cloud/v1

- API key: Your Luma Cloud key, entered in the client's secret field

- Model ID: MODEL_ID_FROM_CATALOG

## Optional agent check

```text
Read README.md in this test folder and summarize its first paragraph. Do not edit files, run shell commands, or access the network.
```

Create a disposable folder containing a short README.md first. Approve only the file read. Check that a tool result and a final answer both appear.

## Verify

- Before using an agent on your project, try one read-only file task in a disposable folder. Confirm the tool result and final answer, keeping action approval enabled.

- Confirm a completed task and matching API usage. If text works but tool calls fail, the integration is not ready for Roo agent tasks.

## Limits

- Roo's documented tool protocol is native tool calling only. There is no XML fallback for a model without tools.

- Do not enable vision or computer-use options unless the chosen model supports them.

- Local token prices are estimates; Dashboard → API records Luma Cloud charges.

## Troubleshooting

### The model answers in prose instead of calling a tool

Use a model documented to support native tool calling. Roo has no XML fallback. Retry only the read-only check after correcting the model; do not work around it by granting broader permissions.

### Context or output-token validation fails

Compare Roo's Model Configuration limits with the selected model's actual limits. Reduce the output budget or shorten the task. Do not copy token limits from an unrelated model.

### 401 or invalid API key

Paste the complete Luma Cloud API key again without quotes, spaces, or a Bearer prefix. Confirm that the same key is still active in Dashboard → API. Your dashboard password and Google sign-in are not API keys.

### Model not found or access denied

Copy the exact model ID available to this key from the authenticated catalog. MODEL_ID_FROM_CATALOG is a placeholder, not a model name. Do not substitute a display label or copy an ID from another provider.

### The request is limited or cannot be funded

Read the error message and check the key's balance or subscription quota in the dashboard. Wait for the stated retry time when provided. Repeatedly creating keys or re-entering the same credentials does not add quota.

## Official client documentation

- [Roo Code: OpenAI-compatible providers and tool requirements](https://roocodeinc.github.io/Roo-Code/providers/openai-compatible/)