# How to set up Cursor with LiteLLM

This guide connects Cursor to a LiteLLM proxy, one you run yourself or one your team already hosts. Cursor takes one base URL and one API key in its settings.

**The tldr version**

1.  Cursor Settings, then Models, then expand API Keys
    
2.  Turn on Override OpenAI Base URL and set it to `https://your-gateway.example.com/cursor`
    
3.  Turn on OpenAI API Key, paste a LiteLLM key, confirm the prompt
    
4.  Add Custom Model, and type the `model_name` from your `config.yaml`
    
5.  Pick that model in the model picker and send a message
    

If you prefer to watch the tutorial instead:

[Watch it on YouTube](https://youtu.be/oNkMgelVsEA)

The steps below are the ones in the video, so you can move between the two.

## Requirements

You need Cursor recent enough to have a **Models** page under Cursor Settings, and a LiteLLM gateway. Docker builds that gateway in section 6 if you do not have one; skip Docker entirely if your team already hosts one.

> **The one that catches people out.** The gateway has to be reachable from the public internet. Cursor does not call your model from your laptop, its own backend makes the request, so `http://localhost:4000` is not reachable. Section 7 provides tips on how to make a publicly available URL.

Versions used: LiteLLM `main-stable`, UI v1.99.0, DB Postgres 16-alpine.

## Let's get started!

If a gateway is already running somewhere your Cursor can reach, sections 1 to 5 are enough. If you don't have a gateway running, jump to section 6, build the gateway, then come back to section 1.

## 1\. Open the Models page in Cursor

The gear icon in the top right opens Cursor Settings. Everything in this guide lives under **Models**.

![Cursor Settings open on the Models page, where every step in this guide happens](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/44cd04f2-ee1d-4d7a-9d43-417e56a86c33.png align="center")

## 2\. Point Cursor at the gateway

Scroll down to **API Keys** and expand it. Then put your gateway URL in the base URL field with `/cursor` on the end, and the per-user API key from the LiteLLM gateway(more on it below). Turn on: **OpenAI API Key**, and **Override OpenAI Base URL toggles**.

```plaintext
https://your-gateway.example.com/cursor
```

![](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/b509854a-e9fe-4abc-b37c-b79c1536dc1d.png align="center")

`/cursor`**.** Is the route LiteLLM exposes for Cursor specifically.

## 3\. Add your key and enable it

Paste a LiteLLM key into the **OpenAI API Key** field and save it. Use a virtual key from the gateway's Virtual Keys page if you have one.

Cursor then asks you to confirm. Say yes.

![Cursor's confirmation dialog after saving a LiteLLM key, warning that Tab, Apply from Chat and Agent stay on Cursor's own models](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/f31079b0-bcf2-4605-b49a-608fbd40e20a.png align="center")

The dialog warns that Tab, Apply from Chat and Agent run on Cursor's own models and cannot be billed to your key. Whereas, Chat and the model picker route through your gateway.

## 4\. Add the model names your gateway serves

Cursor's model list is its own. If a `model_name` from your config happens to match something Cursor already lists, it shows up on its own. In some case, it might not allow to use the same model names as the built-in model names in Cursor. In that case, you will have to add a custom model name.

Scroll to the bottom of the model list, click **Add Custom Model**, and type the name exactly as it appears in `config.yaml` or public model names from the created models in the gateway.

![The Add Custom Model box in Cursor with a gateway model name typed exactly as it appears in config.yaml](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/05396a2d-a6ff-4a79-b2e5-5f070fccd62f.png align="center")

## 5\. Send a message and check the logs

Open a chat, click the model picker, and pick one of your models.

![Cursor's chat model picker with a gateway-served model selected](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/2686b64b-a88c-4b2a-ba5f-0a56d5e88d81.png align="center")

Now go to the gateway UI, open **Logs** under Observability, and narrow the time filter to the last fifteen minutes. Your request is there with a cost against it.

![The Logs page in the LiteLLM UI, filtered to the last fifteen minutes, showing the request Cursor just sent](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/736bd60d-f16e-45da-82ec-c2bbe0fd4e20.png align="center")

Click a row for the detail and now you can see which key sent it, how many tokens went out and came back, what it cost, how long it took, and how much of the prompt was served from cache.

![A single LiteLLM log entry expanded, showing the key, token counts, cost, latency and cache usage](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/8316271d-9156-41e1-a4c1-052eed1f42e3.png align="center")

The Tags row shows `User-Agent: Cursor`, which indicates that it was Cursor traffic.

## 6\. No gateway yet? Let's run one

Start a new project directory, or create these three files in your existing project directory.

### config.yaml

```yaml
model_list:
  - model_name: litellm-gpt-5.6-terra
    litellm_params:
      model: openai/gpt-5.6-terra
      api_key: os.environ/OPENAI_API_KEY
  - model_name: litellm-claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

litellm_settings:
  drop_params: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

  # Coding turns stream for a long time. Do not cut them off.
  request_timeout: 600

router_settings:
  num_retries: 3
  cooldown_time: 30
```

`model_name`**.** This is the name Cursor sends and the name you type into Add Custom Model. Prefixing them with `litellm-` keeps your model names from colliding with Cursor's built-in list, and when you see one in a log you know where it came from.

`model`**.** The provider's own name for the model, with the provider in front. LiteLLM uses this to decide which API to call and how to shape the request. You can find the full list of [models supported here](https://models.litellm.ai).

`drop_params: true`**.** Coding agents send parameters that not every provider accepts. This line drops them instead of failing the request.

`request_timeout: 600`**.** An agentic turn can stream for minutes. The default cuts it off well before that.

### .env

```plaintext
LITELLM_MASTER_KEY=sk-your-own-long-random-string
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

The master key is the only required variable, along with any provider api key needed for the models listed in the config.yaml.

### docker-compose.yml

```yaml
name: litellm-coding-agents

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    restart: unless-stopped
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    ports:
      - "4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://litellm:litellm@postgres:5432/litellm
      STORE_MODEL_IN_DB: "True"
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:4000/health/liveliness').status==200 else 1)\""]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    # Deliberately not published to the host. Nothing outside this network
    # needs it, and a 5432 collision is an annoying afternoon.
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm
      POSTGRES_DB: litellm
    volumes:
      - litellm-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
      interval: 5s
      timeout: 5s
      retries: 20

volumes:
  litellm-pgdata:
```

Postgres DB allows UI access to make virtual keys, budgets and the logs we saw in section 5.

`STORE_MODEL_IN_DB: "True"`**.** Lets you add models from the UI. Models added that way live in the database.

Bring it up:

```bash
docker compose up -d
```

Then check it is actually serving:

```bash
curl -s http://localhost:4000/health/liveliness
```

You want `"I'm alive!"` back.

A quick tip: if something else already holds port 4000, find it with `lsof -nP -iTCP:4000 -sTCP:LISTEN` and either stop it or change the published port in `docker-compose.yml`.

## 7\. Give the local gateway a public URL

Cursor's backend has to reach the gateway, so a local port needs a tunnel in front of it. You can assign a public URL to your locally deployed gateway using either ngrok or cloudflared.  
  
ngrok:

```bash
ngrok http 4000 --log=stdout
```

![An ngrok session in the terminal printing the public HTTPS forwarding URL for port 4000](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/9eed0733-937c-4541-a61d-da7d87791da5.png align="center")

cloudflared:

```bash
cloudflared tunnel --url http://localhost:4000
```

Either one prints an HTTPS URL. That URL, plus `/cursor` goes into the base URL field from section 2.

![](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/f7035ba6-4c06-408f-8010-44425b34ce10.png align="center")

A free tunnel URL changes every time you restart the tunnel, and Cursor will need the new one. For anything beyond trying this out, put the gateway on a host with a real domain.

## 8\. Adding a model from the LiteLLM UI

With `STORE_MODEL_IN_DB` on in docker-compose.yml, **Models + Endpoints** has an **Add Model** tab that writes to the database instead.

![The Add Model tab in LiteLLM's Models and Endpoints page, showing the LiteLLM Model Name and Public Model Name fields](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/f0f5da3c-7c40-42f9-b65e-c98b58bbade6.png align="center")

**LiteLLM Model Name** is the provider's name for the model, the string LiteLLM will send upstream. **Public Model Name** is what we can assing and what Cursor sends. Mapping `litellm-gpt-5.6-luna` to `gpt-5.6-luna` is the UI equivalent of the `model_name` / `model` pair in `config.yaml`.

Scroll down for the credentials.

![The credentials fields further down the LiteLLM Add Model form](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/bd526b6d-fa0f-4fc9-8bd8-f362b8fa1895.png align="center")

Save it, add the public model name to Cursor with **Add Custom Model** the way you did in section 4. Test a short prompt in the chat and the model sends the response.

![A Cursor chat answering through the model that was just added from the LiteLLM UI](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/fa4577f1-4585-4639-b0ff-48bf36a4e174.png align="center")

## Advanced options

### Manage usage with virtual keys

Create a key per developer under **Virtual Keys**, give each one a budget and a list of models it is allowed to use, and hand that to your teammates. The Key Alias column in the logs gives you details of the usage.

### Using different models

Anything LiteLLM supports works here, not just OpenAI. Add a block to `model_list`, give it a `model_name` that starts with `litellm-`, restart, and add that name to Cursor. Cursor is talking to an OpenAI-shaped endpoint, and it could Claude or Gemini or a local model.

### No base URL field? Use the Azure OpenAI panel

Some Cursor builds do not show **Override OpenAI Base URL**. The **Azure OpenAI** panel underneath it takes the same three pieces of information and gets you to the same place.

![](https://cdn.hashnode.com/uploads/covers/6a9a78f24e8e4303470be4cf/166f1f7d-414d-4858-a828-f84eb06fe102.png align="center")

One difference, and it is easy to miss: **do not** append `/cursor` here. Base URL is the bare gateway URL. Deployment Name is your public model name, and API Key is the LiteLLM key.

## Additional resources

*   LiteLLM docs: https://docs.litellm.ai
    
*   Cursor tutorial page: https://docs.litellm.ai/docs/tutorials/cursor\_integration
    
*   Gateway quick start: https://docs.litellm.ai/docs/proxy/quick\_start
    
*   Docker quick start: https://docs.litellm.ai/docs/proxy/docker\_quick\_start
    
*   LiteLLM on GitHub: https://github.com/BerriAI/litellm
    
*   Video walkthrough: [Watch it on YouTube](https://youtu.be/oNkMgelVsEA)