olp/docs/integrations/cursor.md

Cursor + OLP

Cursor is an AI-first VS Code fork. It has an "Override OpenAI Base URL" setting that, when populated, routes its default-model traffic to your URL using the OpenAI wire format.

Status: ⚠️ Best-effort.

Reason: Cursor's base-URL override is known to be fragile across releases. Multiple 2025-2026 forum threads document the setting silently reverting, model-list dropdowns not populating from the override URL, and streaming responses falling back to the default backend on parse errors. The behaviour is not specific to OLP — every OpenAI-compatible proxy maintainer documents the same caveats — but Cursor's release cadence is faster than most third-party proxies can test against.

Quick setup

1. Open Cursor → Settings → "Models" → enable OpenAI API Key.

2. Paste your OLP plaintext token into the API Key field.

3. Click "Override OpenAI Base URL" and paste:

   http://127.0.0.1:4567/v1
   

4. Click "Verify". Cursor sends a probe; on success the indicator turns green.

5. Crucial step: in the model list, disable every model that is NOT in your ~/.olp/config.json routing.chains. Cursor's chat will round- robin across enabled models and any model OLP can't route will error.

Replace the API key with the plaintext token printed by olp-keys keygen --name=cursor. Family members on the LAN should substitute the OLP host's IP for 127.0.0.1 (or use olp-connect <ip>).

Known issues

• Override URL silently reverts on Cursor update. Two reported variants: (a) the field empties; (b) the field shows the OLP URL but Cursor still hits api.openai.com under the hood. Workaround: after every Cursor update, re-open settings, click "Verify" again, and check the OLP server's /health for incoming probe requests.

• Model-list dropdown does not populate from the override URL. Cursor hardcodes its model list rather than reading GET /v1/models. This is why step 5 above is required — there is no way to make Cursor "discover" your models. You have to disable each model individually that OLP can't serve.

• Streaming response parsing is stricter than OpenAI's actual SSE spec. Cursor occasionally falls back to the default backend if the SSE stream contains a slightly malformed chunk (e.g. an empty data: line that OpenAI's API does emit but Cursor's parser doesn't expect). OLP's SSE emitter follows the spec; this is on Cursor's side. If you see traffic hitting api.openai.com despite the override, this is the most likely cause.

• Cursor's "Tab" autocomplete is NOT covered by the override. Tab completion uses a Cursor-proprietary endpoint that is not affected by the OpenAI base URL setting. Only the chat panel is. This is documented Cursor behaviour and is not a bug.

OLP-specific notes

Cursor sends model: "gpt-4" or model: "gpt-3.5-turbo" (legacy aliases) unless you explicitly select another from its dropdown. Add aliases to your ~/.olp/config.json routing.chains so these route somewhere sane:

{
  "routing": {
    "chains": {
      "gpt-4":         [ { "provider": "openai", "model": "gpt-5" } ],
      "gpt-3.5-turbo": [ { "provider": "openai", "model": "gpt-5-mini" } ]
    }
  }
}

(Substitute the OpenAI Codex model names listed by olp models.)

Recommendation

Do not engineer workarounds for Cursor-side bugs. Cursor's release cadence will fix or re-break the override URL handling at unpredictable intervals. If your daily-driver flow is unreliable, switch to Cline (see cline.md) — it has a stable OpenAI-compatible provider that does not break across releases.

Test it

curl -sI -X POST http://127.0.0.1:4567/v1/chat/completions \
  -H "Authorization: Bearer olp_XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"ok"}],"max_tokens":5}' \
  | grep -i x-olp

After hitting "Send" in Cursor's chat, check the OLP server's recent requests via:

npx olp logs 10

If you don't see Cursor's request in the audit log, traffic isn't reaching OLP — re-check the override URL.

Cross-references

• Cursor forum threads on base-URL fragility: https://forum.cursor.com/ (search "OpenAI base URL")
• olp-connect writes Cursor's cursorrc if detected, but cannot guarantee the override survives a Cursor update.