cursor-api-proxy

OpenAI-compatible proxy for Cursor CLI. Run it on localhost and point any LLM client (OpenAI SDK, LiteLLM, LangChain, etc.) at it like a normal chat API.

One npm package, two uses: import it as an SDK, or run the CLI to start the server. Same behavior either way.

This is not the Cursor IDE. The HTTP API will not attach your repo, @codebase, or host shell the way the desktop app does. See Local workspace and agent frameworks.

Prerequisites

• Node.js 18+

• Cursor agent CLI (cursor-agent or agent). This package does not install or bundle the CLI. Install and set it up separately. The proxy prefers cursor-agent on PATH, then falls back to agent. Set CURSOR_AGENT_BIN when another vendor also installs an agent command.

  curl https://cursor.com/install -fsS | bash
  agent login
  agent --list-models
  

  For automation, set CURSOR_API_KEY instead of using agent login.

Install

From npm (SDK in another project):

npm install cursor-api-proxy

From source:

git clone <this-repo>
cd cursor-api-proxy
npm install
npm run build

Run the proxy (CLI)

Start the server so the API is available for the SDK or any HTTP client:

npx cursor-api-proxy
# or from repo: npm start / node dist/cli.js

Inspect completed requests without opening the dashboard:

cursor-api-proxy requests
cursor-api-proxy requests --limit 50
cursor-api-proxy requests --watch --interval 1

The command reads CURSOR_BRIDGE_SESSIONS_LOG (default ~/.cursor-api-proxy/sessions.log) directly, so the proxy does not need to be running. It shows completion time, method, status, remote address, and path. Set NO_COLOR=1 for plain output.

To expose on your network (e.g. Tailscale):

npx cursor-api-proxy --tailscale

By default the server listens on http://127.0.0.1:8765. Set CURSOR_BRIDGE_API_KEY to require that key on requests, sent as Authorization: Bearer <key> (OpenAI SDKs) or x-api-key: <key> (Anthropic SDKs). A missing or wrong key gets a 401 in the error shape of the API that was called. /healthz and the dashboard need no key.

HTTPS with Tailscale (MagicDNS)

Serve over HTTPS so browsers and clients trust the connection (e.g. https://macbook.tail4048eb.ts.net:8765):

1. Generate Tailscale certificates on this machine (run from the project directory or where you want the cert files):

   sudo tailscale cert macbook.tail4048eb.ts.net
   

   This creates macbook.tail4048eb.ts.net.crt and macbook.tail4048eb.ts.net.key in the current directory.

2. Run the proxy with TLS and optional Tailscale bind:

   export CURSOR_BRIDGE_API_KEY=your-secret
   export CURSOR_BRIDGE_TLS_CERT=/path/to/macbook.tail4048eb.ts.net.crt
   export CURSOR_BRIDGE_TLS_KEY=/path/to/macbook.tail4048eb.ts.net.key
   # Bind to Tailscale IP so the service is only on the tailnet (optional):
   export CURSOR_BRIDGE_HOST=100.123.47.103
   npm start
   

   Or bind to all interfaces and use HTTPS:

   CURSOR_BRIDGE_TLS_CERT=./macbook.tail4048eb.ts.net.crt \
   CURSOR_BRIDGE_TLS_KEY=./macbook.tail4048eb.ts.net.key \
   CURSOR_BRIDGE_API_KEY=your-secret \
   npm start -- --tailscale
   

3. Access the API from any device on your tailnet:

   • Base URL: https://macbook.tail4048eb.ts.net:8765/v1 (use your MagicDNS name and port)
   • Browsers show a padlock with no certificate warnings when using Tailscale-issued certs.

Local workspace and agent frameworks

Point OpenClaw, LangChain, or your own agent runtime at this proxy with a normal baseUrl and apiKey, and you get a cloud model behind an OpenAI-shaped HTTP API. That is not the Cursor IDE, which indexes and acts on a local workspace.

The model only sees what you send: messages, optional tool schemas, and tool results your client executes and returns. No automatic filesystem, repo layout, or @codebase injection from the proxy alone. By default the proxy also prepends a short bridge context block (see CURSOR_BRIDGE_CONTEXT_PREAMBLE) so the model knows the request came through this HTTP bridge and which workspace paths apply.

File reads, shell commands, and directory listings only happen when your agent framework implements tools, runs them on the host, and sends outputs back in follow-up messages. The proxy does not do that for you.

Optional server-side workspace: the Cursor CLI may run with a workspace directory (CURSOR_BRIDGE_WORKSPACE, per-request X-Cursor-Workspace). By default, CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE=true runs the CLI in an empty temp directory so it does not read or write your real project. The proxy also overrides HOME, USERPROFILE, and CURSOR_CONFIG_DIR so the agent does not load global or project rules from elsewhere. That temp home is a separate directory next to the empty workspace, never inside it. On macOS it links your real ~/Library/Keychains so the CLI can still read and save its login, and keeping it outside the workspace keeps that link out of anything the agent lists, searches, or edits as the project. Set it to false if you want the CLI to see a path on the machine where the proxy runs. That is still not IDE indexing. See the env table below.

For agents that need local context: use client-side tools (read_file, run_terminal_cmd) and pass results as tool messages; add RAG or retrieval and inject snippets into user content; or paste relevant files into the prompt. There is no built-in way to sync an entire workspace through the proxy today.

Client tool passthrough (ACP)

Without ACP (the default CLI mode), responses never contain tool calls. The proxy lists the request's function tools in the prompt for reference only and tells the model it cannot call them. Large tool sets are trimmed to about 8,000 characters: each tool gets its name and a description of up to 200 characters while they fit (any beyond that are only counted), and full schemas fill the space left, in request order.

Set CURSOR_BRIDGE_USE_ACP=true to receive structured client tool calls. Tool-bearing requests require a Cursor ACP build that advertises HTTP MCP support. The proxy supports:

• Chat Completions tools / legacy functions → message.tool_calls; resume with role: "tool" and tool_call_id.
• Responses flat function tools → function_call output items; resume with previous_response_id and function_call_output, or resend the whole conversation with the function_call_output items appended and no previous_response_id (Codex CLI does this with store: false).
• Responses namespace tool groups (Codex CLI) are flattened for the agent and reported back as the member's bare name plus namespace. Host-side builtins such as web_search are dropped, and tool_choice: "required" with no callable tool left returns 400.
• Freeform custom tools (Responses {type: "custom", name, format}, such as Codex CLI's apply_patch, or Chat {type: "custom", custom: {...}}) reach the agent as a function with one input string, the grammar copied into its description. Calls come back as custom_tool_call items carrying the raw input (streamed as response.custom_tool_call_input.delta / .done), or as Chat type: "custom" tool calls. Resume like a function call, with custom_tool_call_output items (Responses, also in a resent conversation) or a role: "tool" message (Chat). tool_choice: {type: "custom", name} selects one.
• Anthropic tools with input_schema → tool_use; resume with tool_result. Anthropic-defined tools (any type other than custom, such as web_search_20250305 or bash_20250124) are dropped like host-side builtins. A tool_choice naming a dropped tool, or any with no client tool left, returns 400.
• With CURSOR_BRIDGE_VERBOSE=true, every request logs the declared tools it dropped because the agent cannot run them.
• Sync and streaming output, mixed text plus tools, parallel calls, multiple rounds, named/required/none choices.

The proxy exposes each request's schemas through a random, bearer-authenticated MCP URL bound only to 127.0.0.1. It never executes caller tools. It parks Cursor's MCP call, returns the native API tool call to your framework, then delivers your framework's result back to the same live ACP turn. Proxy-owned MCP permission is allowed once; built-in and other tool permissions remain rejected.

Tool loops are stateful and in-process:

• Keep the same proxy process alive between the call and its result.
• Submit results before CURSOR_BRIDGE_TIMEOUT_MS. Expiration, restart, unknown IDs, or wrong API-key owner return HTTP 409.
• Responses requests without previous_response_id are matched on call_id instead: only the function_call_output items after the latest user message resume a parked call, so outputs from finished turns stay history. If none of them is parked (expired, restarted, another API-key owner), the proxy starts a new ACP session from the conversation you sent, which already holds the tool results, instead of returning 409. Outputs sent with no user message still return 409. A new user turn also closes any parked call that the conversation has moved past.
• Parallel results may arrive together or incrementally. The original account/profile and temporary workspace stay attached until the turn finishes.
• A client disconnect while a turn is active cancels the ACP child and removes temporary state.
• Responses API objects remain externally completed while an internal ACP turn waits for function_call_output.

Minimal Chat Completions loop:

const messages = [{ role: "user", content: "Weather in Paris?" }];
const tools = [{
  type: "function",
  function: {
    name: "weather",
    parameters: {
      type: "object",
      properties: { city: { type: "string" } },
      required: ["city"],
    },
  },
}];

const first = await client.chat.completions.create({
  model: "auto",
  messages,
  tools,
});
const assistant = first.choices[0].message;
messages.push(assistant);
for (const call of assistant.tool_calls ?? []) {
  const args = JSON.parse(call.function.arguments);
  const output = await getWeather(args.city); // executed by your app
  messages.push({ role: "tool", tool_call_id: call.id, content: output });
}
const final = await client.chat.completions.create({ model: "auto", messages });

Image and video input (ACP)

With CURSOR_BRIDGE_USE_ACP=true, images are forwarded to the model as native ACP image blocks:

• Chat Completions image_url, Responses input_image, and Anthropic image (base64 or URL sources).
• data: URLs and public https:// URLs on port 443. Remote URLs that resolve to loopback, private, link-local, or other non-public addresses are rejected, every redirect is re-checked, and downloads are capped at 10 MiB per image (40 MiB per video) with a 30 s deadline.
• PNG, JPEG, WebP, and GIF images. MP4, QuickTime, and WebM video is sampled into up to 3 frames (about 5 s apart), which needs ffmpeg on the proxy host (included in the Docker image).
• At most 12 images per request, newest first; each video counts as 3. Older images in the history become text placeholders, so long conversations keep working. Only a latest message that cannot fit on its own returns 422.
• Media the proxy cannot use (an unsupported type, a source that is too large or cannot be fetched, a video that does not decode) returns 422 unsupported_media with the reason. A failure on the proxy host itself, such as a temp directory it cannot create, returns 500 internal_error; the detail goes to the server log only.

Without ACP, media stays a text placeholder in the prompt and the proxy logs a warning; the request still succeeds.

Use as SDK in another project

Install the package and set up the Cursor agent CLI (see Prerequisites). With the default URL, the proxy starts in the background automatically if it is not already running. You can still start it yourself with npx cursor-api-proxy or set CURSOR_PROXY_URL to point at an existing proxy (then the SDK will not start another).

• Base URL: http://127.0.0.1:8765/v1 (override with CURSOR_PROXY_URL or options).
• API key: use any value (e.g. unused), or set CURSOR_BRIDGE_API_KEY and pass it in options or env.
• Disable auto-start: pass startProxy: false (or use a custom baseUrl) if you run the proxy yourself and don't want the SDK to start it.
• Shutdown: when the SDK starts the proxy, it stops it on process exit or normal termination signals. stopManagedProxy() is still available for earlier shutdown. SIGKILL cannot be intercepted.

OpenAI SDK + helper

Optional consumer-side example. openai is not a dependency of cursor-api-proxy; install it only in the app where you run this.

import OpenAI from "openai";
import { getOpenAIOptionsAsync } from "cursor-api-proxy";

const opts = await getOpenAIOptionsAsync(); // starts proxy if needed
const client = new OpenAI(opts);

const completion = await client.chat.completions.create({
  model: "gpt-5.2",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);

const response = await client.responses.create({
  model: "gpt-5.2",
  input: "Hello",
});
console.log(response.output_text);

For a sync config without auto-start, use getOpenAIOptions() and ensure the proxy is already running.

Minimal client (no OpenAI SDK)

import { createCursorProxyClient } from "cursor-api-proxy";

const proxy = createCursorProxyClient(); // proxy starts on first request if needed
const data = await proxy.chatCompletionsCreate({
  model: "auto",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(data.choices?.[0]?.message?.content);

Raw OpenAI client (no SDK import from this package)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:8765/v1",
  apiKey: process.env.CURSOR_BRIDGE_API_KEY || "unused",
});
// Start the proxy yourself (npx cursor-api-proxy) or use the helpers above for auto-start.

Endpoints

Method	Path	Description
GET	/health	Server and config info
GET	/v1/models	List Cursor models (from agent --list-models)
POST	/v1/chat/completions	Chat + native tool_calls; supports stream: true
POST	/v1/responses	Responses text + function_call; supports semantic SSE streaming
POST	/v1/messages	Anthropic Messages + tool_use; supports stream: true

Reasoning effort

OpenAI clients can select a Cursor reasoning variant without hard-coding its full Cursor model ID:

• Chat Completions: reasoning_effort
• Responses: reasoning.effort

For example, model gpt-5.6-sol with effort high resolves to gpt-5.6-sol-high when that ID is present in the live agent --list-models catalog. Explicit variants can be retargeted, and -fast is preserved (gpt-5.6-sol-high-fast plus low resolves to gpt-5.6-sol-low-fast). Supported spellings are none/off, minimal, low, medium, high, xhigh/extra-high, and max. The API returns 400 unsupported_reasoning_effort instead of silently choosing another model when the requested family does not offer that level.

Usage and token fields: responses may include usage token fields (prompt_tokens/completion_tokens for Chat Completions, input_tokens/output_tokens for Responses). These are heuristic estimates (character count ÷ 4), not Cursor billing meters. Do not use them for invoicing.

Environment variables

One module resolves aliases, defaults, path resolution, platform fallbacks, and --tailscale host behavior before the server starts.

Variable	Default	Description
CURSOR_BRIDGE_HOST	127.0.0.1	Bind address
CURSOR_BRIDGE_PORT	8765	Port
CURSOR_BRIDGE_API_KEY	—	If set, require this key on requests, as Authorization: Bearer <key> or x-api-key: <key>. When a request sends both, the Bearer token is the key. /healthz and the dashboard need no key.
CURSOR_API_KEY / CURSOR_AUTH_TOKEN	—	Cursor access token passed to spawned CLI/ACP children (automation, headless). Same value can be used for both names.
CURSOR_BRIDGE_WORKSPACE	process cwd	Base workspace directory for Cursor CLI. With CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE=false, header X-Cursor-Workspace must point to an existing directory under this path (after resolving real paths), or the request fails with 400 invalid_workspace.
CURSOR_BRIDGE_MODE	—	Server default for Cursor CLI --mode: agent, ask, or plan. If unset, default is ask. Env wins over CLI --mode when both are set. Per request, JSON body mode or header X-Cursor-Mode overrides (precedence: body → header → DSH auto-mode → this env → --mode → ask). Invalid value → startup error. With agent (or plan) and real workspace, the CLI may read/write files under CURSOR_BRIDGE_WORKSPACE / cwd. See CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE.
CURSOR_BRIDGE_DSH_AUTO_MODE	false	When enabled, requests whose system/developer content contains the DSH system marker use Cursor plan while the plan marker is present and agent otherwise. Ordinary user content is never inspected. Explicit body/header modes still win.
CURSOR_BRIDGE_DSH_SYSTEM_MARKER	You are an AI agent powered by DeepSeek Harness.	Exact substring identifying trusted DSH-owned system/developer content for auto-mode.

Notes:

• The login subcommand depends on chrome-launcher; its dependency tree may pull typings into production installs. Run npm audit before release; upstream may move types to devDependencies over time.
• --tailscale changes the default host to 0.0.0.0 only when CURSOR_BRIDGE_HOST is not already set.
• ACP session/request_permission uses allow-once only for the per-turn proxy-owned client-tool MCP invocation. Built-in and other tools use reject-once.
• Relative paths such as CURSOR_BRIDGE_WORKSPACE, CURSOR_BRIDGE_SESSIONS_LOG, CURSOR_BRIDGE_TLS_CERT, and CURSOR_BRIDGE_TLS_KEY are resolved from the current working directory.

Windows command line limits

Two different limits matter:

1. cmd.exe, about 8191 characters. If the proxy invokes the agent through cmd.exe, long prompts can fail before the process starts.
2. CreateProcess, about 32,767 characters for the entire command line (executable path plus all arguments), even when spawning node.exe and the script directly.

When agent.cmd is used (e.g. under %LOCALAPPDATA%\cursor-agent\), the proxy auto-detects the versioned layout (versions/YYYY.MM.DD-commit/) and spawns node.exe + index.js from the latest version directly, bypassing cmd.exe. If that does not apply, set both CURSOR_AGENT_NODE and CURSOR_AGENT_SCRIPT so the proxy spawns Node with the script and args without cmd.exe.

Very large prompts can still hit the CreateProcess cap and produce spawn ENAMETOOLONG. The proxy mitigates that on Windows by truncating the start of the prompt while keeping the tail (recent context), prepending a short notice, logging a warning, and optionally exposing X-Cursor-Proxy-Prompt-Truncated: true. Tune the budget with CURSOR_BRIDGE_WIN_CMDLINE_MAX (default 30000). ACP or stdin prompt avoids argv length limits for prompt delivery.

Example (adjust paths to your install):

set CURSOR_AGENT_NODE=C:\Program Files\nodejs\node.exe
set CURSOR_AGENT_SCRIPT=C:\path\to\Cursor\resources\agent\agent.cmd
# or for cursor-agent versioned layout:
# set CURSOR_AGENT_NODE=%LOCALAPPDATA%\cursor-agent\versions\2026.03.11-6dfa30c\node.exe
# set CURSOR_AGENT_SCRIPT=%LOCALAPPDATA%\cursor-agent\versions\2026.03.11-6dfa30c\index.js

CLI flags:

Flag	Description
--tailscale	Bind to 0.0.0.0 for access from tailnet/LAN (unless CURSOR_BRIDGE_HOST is already set)
--verbose	Enable verbose logs (request/response previews + model resolution chain)
--mode	Default Cursor CLI mode: agent, ask, or plan (default ask if omitted). Overridden by CURSOR_BRIDGE_MODE when set.
-h, --help	Show CLI usage

Optional per-request overrides:

• Header X-Cursor-Workspace: <path>, subdirectory of CURSOR_BRIDGE_WORKSPACE when using a real workspace (see CURSOR_BRIDGE_CHAT_ONLY_WORKSPACE). In chat-only mode the agent cwd stays a temp dir and this header is ignored; the preamble leaves its path out too.
• Header X-Cursor-Proxy-Client: <label> (optional), shown as client= if X-Cursor-Invoke-From is not set.
• Header X-Cursor-Invoke-From: <label> (optional), preferred for client= (e.g. claude-cli, cursor-claude-extension).
• Header X-Cursor-Mode: <agent|ask|plan> or JSON body field mode, execution mode for that request (body wins over header).

CLI subcommands (see cursor-api-proxy --help): login <name>, accounts (list), logout, usage, reset-hwid (see --help for options). Flags above still apply to the server entrypoint.

Multi-account setup

Use multiple Cursor accounts to spread load and stay under usage limits. The proxy includes a built-in account manager.

Adding accounts

npx cursor-api-proxy login account1

Opens an isolated browser login. Session saves under ~/.cursor-api-proxy/accounts/ on macOS/Linux, or %USERPROFILE%\.cursor-api-proxy\accounts\ on Windows.

Repeat for more accounts:

npx cursor-api-proxy login account2
npx cursor-api-proxy login account3

When you start the proxy (npx cursor-api-proxy), it finds all accounts under that directory and adds them to the rotation pool.

Manual config directories

If you already have separate configuration folders (or want to specify them explicitly), override auto-discovery with CURSOR_CONFIG_DIRS:

CURSOR_CONFIG_DIRS=/path/to/cursor-agent-1,/path/to/cursor-agent-2 npm start

Modes of operation

Single port, round-robin rotation (default)

The proxy listens on one port and rotates through available accounts for each request, picking the least busy account. Active by default when multiple accounts are found.

Multi-port (one server per account)

For explicit client-to-account mapping, use multi-port mode. The proxy spawns multiple instances on incrementing ports starting from CURSOR_BRIDGE_PORT.

CURSOR_BRIDGE_MULTI_PORT=true CURSOR_BRIDGE_PORT=8765 npm start

account1 on 8765, account2 on 8766, and so on.

Rate and plan limits

When the agent's output shows a rate limit, the account rests for a minute and the pool prefers the others. When a Cursor plan is used up, the agent answers only "Upgrade your plan to continue" (or "Add a payment method to continue"), or the CLI fails with "prepaid balance is used up"; the proxy returns that as HTTP 429 with code cursor_plan_limit on every API (in a stream, as the error that ends it, never as answer text) and rests the account for 15 minutes, so a retry goes to another account. Plan limits are per model: an account that hit it for one model may still answer others.

Streaming

The proxy supports stream: true on POST /v1/chat/completions, POST /v1/responses, and POST /v1/messages. Chat Completions and Messages return Server-Sent Events (SSE) in OpenAI/Anthropic streaming formats. Responses uses OpenAI Responses semantic SSE events (response.created, response.output_text.delta, …), each with a sequence_number that starts at 0 for every response and goes up by one per event. Cursor CLI emits incremental deltas plus a final full message; the proxy deduplicates output so clients receive each chunk only once.

While the agent is silent (thinking / tools, no tokens yet), the proxy writes SSE comment heartbeats (: keepalive) every 15s so clients with idle timeouts — notably Codex CLI — do not drop the stream. Codex stream_idle_timeout_ms is usually unnecessary. Long turns still need CURSOR_BRIDGE_TIMEOUT_MS above the run wall-clock.

When the agent fails after a stream has started, the stream ends with the API's own error: Chat Completions sends a chunk holding only error ({ message, type, param, code }) and then data: [DONE]; Responses sends response.failed, whose response has status: "failed" and error: { code, message }; Messages sends an error event with { "type": "error", "error": { type, message, code } }. Before a stream starts, the same failure is an HTTP error in that API's shape. The code says what failed, e.g. cursor_cli_error when the agent cannot be started (its binary is missing or not executable), exits non-zero, or the proxy's model check (agent --list-models) fails. Error messages leave out the CLI's output and paths on the proxy host; the proxy logs those instead.

Test streaming from repo root, with the proxy running:

node examples/test-stream.mjs

See examples/README.md for details.

Docker

Requires a Cursor Dashboard API key (CURSOR_API_KEY from https://cursor.com/dashboard/integrations).

cp .env.example .env
# set CURSOR_API_KEY=... in .env

docker compose up --build -d

Listens on http://127.0.0.1:8765 by default (host bind via HOST_BIND / HOST_PORT in .env). Image installs the Cursor agent CLI and runs the proxy as a non-root user. Health probes hit /healthz (no API key required).

curl -s http://127.0.0.1:8765/healthz
curl -s http://127.0.0.1:8765/v1/models

License

MIT