Aider, Claude Code, Cursor: One LiteLLM Proxy for All

Contents

Figure 1: Aider, Claude Code, Cursor: One LiteLLM Proxy for All — three tools, three protocols, one gateway URL

Here is a fact that makes this setup easier to reason about: Aider already runs on LiteLLM. Its docs say it "uses the litellm package to connect to hundreds of other models" [1]. So "using LiteLLM with Aider" really means one of two things. You can use Aider's built-in LiteLLM support directly, or you can point Aider at a LiteLLM proxy you run yourself. This guide covers the second one, plus Claude Code and Cursor.

I did not run any of these tools, since none are installed here. The settings come from each project's own docs, and my script only checks setups against quoted rules.

Why Put a Proxy in the Middle?

A proxy gives every tool one URL, one key and one place to manage models, budgets and fallbacks. Developers use different editors and models, and you do not want to hand each one a raw provider key. The proxy config lists the models by model_name, and clients ask for those names.

A minimal config entry for an OpenAI-compatible upstream looks like this [5]:

model_list:
  - model_name: my-model
    litellm_params:
      model: openai/<your-model-name>
      api_base: <model-api-base>
      api_key: api-key

Start it with litellm --config /path/to/config.yaml. One gotcha from LiteLLM's docs: if you get a "Not Found Error" calling an OpenAI-compatible upstream, its api_base should end in /v1, for example http://vllm-endpoint.xyz/v1 [5]. Do not append endpoint paths like /v1/embedding, because the client adds them.

Aider: Three Settings

Aider's OpenAI-compatible page gives the recipe [2]:

1. Set OPENAI_API_BASE=<endpoint> and OPENAI_API_KEY=<key>. On Windows use setx and restart your shell.
2. Change into your project directory.
3. Run aider --model openai/<model-name>.

The openai/ prefix matters. LiteLLM uses it to route to an OpenAI-compatible /chat/completions endpoint [5]. Here <model-name> is whatever name your proxy config exposes.

In my checker, forgetting the prefix was the first finding, and asking for a model that is not in the config was the second.

Aider has a built-in answer for the second one: aider --list-models <partial-name> returns the models it knows that match [1]. That is the quickest way to tell "Aider does not know this name" apart from "my proxy does not serve it."

Aider may warn about models it does not recognise. The page only links to its model warnings section without describing them, so expect the warning rather than treating it as the cause [2]. It also does not say how to find the right endpoint value, so use your proxy's URL.

Claude Code: The Anthropic-Format Route

LiteLLM's tutorial uses a different protocol. Claude Code sends requests to /v1/messages in the Anthropic Messages API format, and LiteLLM translates them to each provider's format [3]. The setup:

1. Install the proxy with uv tool install 'litellm[proxy]', and define models in config.yaml.
2. Start it. The page says it runs on http://0.0.0.0:4000.
3. Set the three variables:

export ANTHROPIC_BASE_URL="http://0.0.0.0:4000"
export ANTHROPIC_AUTH_TOKEN="$LITELLM_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

Variable	Value
ANTHROPIC_BASE_URL	Your proxy URL, for example http://localhost:4000
ANTHROPIC_AUTH_TOKEN	Your LiteLLM virtual key
ANTHROPIC_MODEL	A model_name from your config

One gotcha that costs an afternoon: if ANTHROPIC_API_KEY is also set in your shell, unset it for the session, or Claude Code may send that instead of your virtual key [3].

The /model picker is the other trap. It still lists Anthropic's own ids, and Claude Code sends whatever id is selected, so choosing one fails with Invalid model name passed in unless your config also defines that exact name [3]. Either add those names to model_list or keep switching models through ANTHROPIC_MODEL.

Model discovery is opt-in: setting CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 turns on discovery through /v1/models, and without it the picker shows Claude Code's built-in list [4]. Your team's or key's model list still decides which of those models a developer may use [3].

On versions: the SSO gateway sign-in flow documented today requires Claude Code v2.1.195 or later [4]. The environment-variable route above is the older, simpler path and needs no SSO configuration at all.

Cursor: Best Effort

The Cursor page is the most candid of the three. It says "Cursor does not officially support AI Gateways, our work here is best effort from reverse engineering their APIs" [5]. The specifics:

• It covers Ask, Plan and Agent modes. Agent mode with the base-URL override needs LiteLLM v1.97.0 or later, because it translates the Responses API request shapes Cursor's agent sends [5].
• Cursor gates custom API keys by mode and model on its side, so coverage follows what Cursor enables [5].
• The Cursor CLI (agent / cursor-agent) cannot target LiteLLM at all [5].
• Newer Cursor builds may not show the Override OpenAI Base URL setting on every plan [5].

The exact steps are documented, and they are three fields:

1. Settings → Cursor Settings → Models. Enable Override OpenAI Base URL and enter your proxy URL with the /cursor suffix: https://your-litellm-proxy.com/cursor.
2. Create a virtual key in the dashboard and paste it into the OpenAI API Key field.
3. Add a custom model whose name is the Public Model Name from your LiteLLM config, and enable it.

Two Cursor-specific failure modes are worth knowing before you start.

First, the proxy must be reachable from the internet. Cursor sends requests from its own servers, not from your machine, with User-Agent: Cursor/1.0, so a proxy behind a VPN, an IP allowlist or a private address fails from Cursor's side before any request reaches LiteLLM [5].

Second, a custom model name that collides with a built-in one is rejected locally, with The model "X" is already available as "Y" [5]. Add a model_list entry with a distinct public name for the same deployment:

model_list:
  - model_name: litellm-claude-sonnet-5
    litellm_params:
      model: anthropic/claude-sonnet-5

Model variants come for free on v1.97.0+: a trailing -fast and a -thinking-<effort> suffix are stripped and resolved, where <effort> is a reasoning_effort value such as low, high or max [5]. A bare -thinking with no effort level is not resolved and returns Invalid model name unless it has its own entry [5].

If your build has no Override OpenAI Base URL setting, the Azure OpenAI fallback still accepts a custom base URL — the proxy URL with no /cursor suffix, your public model name as the Deployment Name, your virtual key as the API key — and it needs no proxy upgrade because it uses an Azure-compatible route LiteLLM has had since 2023 [5]. Cursor refuses its own models while that toggle is on, which the page calls out as another limitation [5].

Keys: Do Not Hand Out the Master Key

The proxy's master key is an admin credential. A virtual key limits which models a client can reach and can be revoked on its own. Use a virtual key for every tool and every person, and keep the master key for admin calls. Virtual keys are generated by calling /key/generate with the master key [3].

The Cursor and Claude Code pages both ask for a virtual key in the field where a provider key would normally go [3][5], which is the behaviour you want: each tool gets its own identity in the logs, its own model list and its own budget.

A Setup Checklist

1. Pick the protocol the tool speaks: OpenAI-style for Aider, Anthropic Messages for Claude Code, and Cursor's own /cursor route.
2. Make sure the model name the client sends matches a model_name in your config.
3. Keep the openai/ prefix on Aider model names.
4. Use a virtual key per tool, not the master key.
5. Check the proxy version against the tool's requirement — Cursor Agent needs 1.97.0+.
6. For OpenAI-compatible upstreams, end api_base in /v1 if you see "Not Found."
7. Make sure Cursor can reach the proxy from the public internet.
8. Test with a small real task, not just a hello-world prompt.

Common Pitfalls

1. Assuming Aider needs a proxy to use LiteLLM. It already bundles litellm; the proxy is for central control.
2. Dropping the openai/ prefix in Aider. The request never reaches the OpenAI-compatible path.
3. Putting the upstream model id in the client. Clients must send your model_name.
4. Leaving ANTHROPIC_API_KEY exported. Claude Code may prefer it over your virtual key.
5. Choosing an Anthropic id from the /model picker. It fails unless the name exists in your config.
6. Naming a Cursor custom model after a built-in one. Cursor rejects it before the request leaves your machine.
7. Running the proxy on localhost for Cursor. Cursor calls from its backend, not from your laptop.
8. Using the master key because it "just works." Every tool then has admin rights and one shared identity in the logs.

Wrapping Up

Coding tools differ in how they talk to a proxy, but the pattern repeats: one base URL, one key and a model name that must match your config. Aider is the simplest because it already speaks LiteLLM. Claude Code needs a few extra variables and one unset one, and Cursor is best effort with a suffix on the URL and a reachability requirement nobody expects.

Set up one tool, check it works on a real task and use a virtual key from day one.

If you have not stood the gateway up yet, the LiteLLM proxy guide covers the quickstart. The virtual keys and budgets guide shows how to scope a key per tool, the load balancing guide explains what happens when two tools share one deployment, and the error guide covers the 401 that follows a stale key in a config file.

Frequently Asked Questions

Does Aider already use LiteLLM under the hood?

Yes. Aider's own docs say it "uses the litellm package to connect to hundreds of other models", so Aider can call most providers directly with aider --model . Pointing Aider at a LiteLLM proxy you run is a different setup: it uses the OpenAI-compatible path, with OPENAI_API_BASE and OPENAI_API_KEY set and the model prefixed openai/.

Why does Aider say model not found when my LiteLLM config has that model?

Because the openai/ prefix is missing, or the name does not match a model_name in your proxy config. Aider expects aider --model openai/, and the openai/ prefix is what sends the request to an OpenAI-compatible /chat/completions endpoint instead of a native provider. The part after the prefix must be a model_name your config exposes, not the upstream provider's model id.

How do I connect Claude Code to a LiteLLM proxy?

Set ANTHROPIC_BASE_URL to your proxy URL, ANTHROPIC_AUTH_TOKEN to a virtual key, and ANTHROPIC_MODEL to a model_name from your config, then launch claude. Claude Code sends requests to /v1/messages in the Anthropic Messages format and LiteLLM translates them. Unset any ANTHROPIC_API_KEY in your shell first, or Claude Code may send that instead of your virtual key.

Why does the /model picker in Claude Code fail with Invalid model name passed in?

Because the picker lists Anthropic's own model ids, and Claude Code sends whatever id is selected as-is. If that id is not a model_name on your gateway, the request fails. Either add those exact names to model_list or keep switching models through ANTHROPIC_MODEL. Setting CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 turns on model discovery through /v1/models, where supported.

Can Cursor use a LiteLLM proxy?

Only on a best-effort basis. LiteLLM's Cursor page states that Cursor does not officially support AI gateways and that the work is reverse engineered. Ask, Plan and Agent modes work through the Override OpenAI Base URL setting pointed at /cursor with a virtual key, and Agent mode on that path needs LiteLLM v1.97.0 or later. The Cursor CLI cannot target LiteLLM at all.

Should each coding tool get its own LiteLLM virtual key?

Yes. A virtual key from /key/generate can be limited to specific models, which keeps a tool from reaching every model in your config, and it can be revoked without touching anyone else. The master key is an admin credential for calls like /key/generate, so handing it to an editor puts full proxy access in a tool's config file.

Sources

• [1] Aider, Other LLMs — the line "Aider uses the litellm package to connect to hundreds of other models", aider --model <model-name> for any supported model, and aider --list-models <partial-name> for discovering names: aider.chat/docs/llms/other.html
• [2] Aider, OpenAI compatible APIs — OPENAI_API_BASE and OPENAI_API_KEY with setx on Windows, the directory change, aider --model openai/<model-name>, and the pointer to the model warnings section: aider.chat/docs/llms/openai-compat.html
• [3] LiteLLM, Connect Claude Code to LiteLLM — /v1/messages handling in the Anthropic Messages format, the ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ANTHROPIC_MODEL quick reference, the warning to unset ANTHROPIC_API_KEY, the /model picker listing Anthropic ids with Invalid model name passed in, and the note that team or key model restrictions still apply: docs.litellm.ai/docs/proxy/client_setup/claude_code
• [4] LiteLLM, Claude Code gateway reference — CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 as the opt-in for model discovery through /v1/models, the built-in picker list without it, and the Claude Code v2.1.195 minimum for gateway SSO sign-in: docs.litellm.ai/docs/tutorials/claude_code_gateway_reference
• [5] LiteLLM, Cursor integration and OpenAI-compatible endpoints — the "best effort from reverse engineering" statement, supported Ask/Plan/Agent modes, the v1.97.0 requirement and Responses API translation, the <proxy>/cursor base URL, virtual key creation, custom model names colliding with built-ins, -fast and -thinking-<effort> variant stripping, the Cursor CLI limitation, the Azure OpenAI fallback, requests originating from Cursor's servers with User-Agent: Cursor/1.0, and the "Not Found Error" fix requiring an api_base ending in /v1: docs.litellm.ai/docs/tutorials/cursor_integration and docs.litellm.ai/docs/providers/openai_compatible

Related Articles

• LiteLLM Proxy Server: Complete Guide to Running One API for Every LLM Provider
• LiteLLM Virtual Keys and Budgets: Control Who Spends What
• LiteLLM Load Balancing: Your RPM Limit Is a Suggestion