> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openference.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Full guide to using Cursor with Openference — the recommended starting point for most users.

# Cursor

Cursor is one of the best experiences with Openference because of its excellent model picker and "Override OpenAI Base URL" support.

## Step-by-step setup

1. Open Cursor.

2. Go to **Settings** (⌘, on macOS) → **Models**.

3. Turn on **Override OpenAI Base URL**.

4. Enter:

   ```
   https://api.openference.com/v1
   ```

5. Paste your API key into the API Key field.

6. (Recommended) Click **Verify**. It should succeed and populate models.

## Using models

* In the model picker (bottom right or ⌘K), select any model ID shown in Openference's catalog.
* Exact IDs matter — copy them from the [Models page](https://openference.com/models) or from the response of `GET /v1/models`.
* Cursor does not auto-discover models from a custom base URL. You must add each model manually: type the exact model ID into the search field in Settings → Models and click **Add Custom Model**. Avoid names that collide with Cursor's built-in models (e.g. `gpt-5.5`) — use a unique name or the exact Openference ID.

## What works through the custom endpoint

Cursor routes only **chat / plan mode** (the chat panel, ⌘L) through the custom OpenAI base URL. Features like **Composer, inline edit, autocomplete, and Apply** are locked to Cursor's own backend and do not honor the custom API key or base URL. This is a Cursor limitation, not an Openference one — if you need a full coding agent backed by Openference, use Claude Code, Codex CLI, Cline, OpenCode, or Pi instead.

## Recommended models

Start with whatever is currently marked as fast/good value on the Openference Models page. You can switch models instantly without changing any code.

## Common issues

### Verify button fails

* Make sure the URL includes the trailing `/v1`.
* Check that the key is still valid and not model-restricted away from what Cursor expects.
* Try a simple curl to `/v1/models` with the same key. Each model should include `"permission": []`, `"root"`, and `"parent": null`.

### Capacity / overloaded errors

A 529 "Overloaded" response means the model is temporarily at capacity. It does not count against your quota. Wait a moment or try a different model.

### Unexpected model list

Your key may have model restrictions applied. Edit the key in the Openference dashboard.

## One key, many tools

The same key you use in Cursor also works in Claude Code, Cline, your Python scripts, etc.

See the [Compatibility Matrix](/integrations/compatibility-matrix).