DEV Community

Cover image for How to set up Cursor with LiteLLM
Misbah Syed
Misbah Syed

Posted on Originally published at misbahsy.hashnode.dev on

How to set up Cursor with LiteLLM

#litellm #cursor

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

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

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.

https://your-gateway.example.com/cursor
Enter fullscreen mode Exit fullscreen mode

/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

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

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

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

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

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 

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
Enter fullscreen mode Exit fullscreen mode

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.

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 

LITELLM_MASTER_KEY=sk-your-own-long-random-string
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
Enter fullscreen mode Exit fullscreen mode

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 

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:
Enter fullscreen mode Exit fullscreen mode

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:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Then check it is actually serving:

curl -s http://localhost:4000/health/liveliness
Enter fullscreen mode Exit fullscreen mode

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:

ngrok http 4000 --log=stdout
Enter fullscreen mode Exit fullscreen mode

An ngrok session in the terminal printing the public HTTPS forwarding URL for port 4000

cloudflared:

cloudflared tunnel --url http://localhost:4000
Enter fullscreen mode Exit fullscreen mode

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

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

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

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

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.

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

Top comments (0)