# Cursor Setup: Custom OpenAI Base URL

> Point Cursor's custom OpenAI base URL at ZRouter, add your account key, choose models, and learn which Cursor features work through a custom endpoint.

## Manage your account with MCP

To inspect usage or manage ZRouter routers, keys, and enabled limits from your assistant, connect the [account MCP server](/docs/mcp). This manages your ZRouter account without changing the assistant's model provider. The instructions below cover routing model requests instead.

## Compatibility first

**Account keys support text and client-executed function tools.** Cursor compatibility depends on the actual request shape and model. Media in agent requests, provider-hosted tools, and stored or encrypted state remain unsupported. Full Cursor Agent sessions have not been validated; check [account compatibility](/docs/integrations/troubleshooting) before using an agent workflow.

Cursor's custom API keys apply to supported chat models. Tab completion uses Cursor's built-in models. Cursor's own plan and usage rules also apply. See [Cursor API key documentation](https://cursor.com/help/models-and-usage/api-keys).

## Connection requirements

Use a public HTTPS gateway endpoint reachable from Cursor's servers. `localhost`, a LAN address, or a private development server is not sufficient for Cursor's hosted request path. See the [Cursor support team's explanation](https://forum.cursor.com/t/dgx-spark-owners-anyone-successfully-connected-ollama-to-cursor/161258/5).

Create an account API key and fund the balance. Use an exact model ID returned by `/v1/models`; do not assume an example model is enabled.

## Configure Cursor

1. Open **Cursor Settings → Models**.
2. Enter the ZRouter key in the OpenAI API key field.
3. Enable **Override OpenAI Base URL** and set `https://zrouter.si/v1` for supported account requests.
4. Save the configuration. Add or select the gateway model ID in the model list if your installed version permits custom models.
5. Start a new text chat with that model. Inspect ZRouter usage and available request logs after a completed request.

The API key is sent through Cursor's backend to the configured gateway. Avoid putting a provider BYOK secret in this field: it needs the ZRouter gateway credential.

## BYOK and feature boundaries

Customer BYOK requires `X-ZRouter-BYOK: true` and a saved key for the selected provider-qualified model. The basic Cursor override does not provide a documented arbitrary-header setting, so these instructions use gateway-funded credits. Merely saving a BYOK key in ZRouter does not make Cursor requests use it.

Tab, cloud features, and other Cursor services are not redirected simply by changing this base URL. Do not assume every model or Cursor feature can use a custom gateway.

## Troubleshooting

- For 401, check the override is still enabled and the key belongs to ZRouter, not OpenAI.
- For connection failure, confirm public HTTPS reachability from outside your machine.
- For model validation errors, check the exact identifier and your version's custom-model support. Do not rename a model to claim capabilities it lacks.
- For a prepaid hosted-tool or media rejection, disable the unsupported feature and use a supported text workflow.

See [shared troubleshooting](/docs/integrations/troubleshooting). Local ZRouter development is better checked with curl or an SDK until a public HTTPS endpoint is available.