Skip to content

cursorpipe v2

OpenAI-compatible HTTP server powered by the official Cursor Python SDK.

Point any OpenAI-compatible client at http://localhost:8080 and use Cursor's frontier models without changing a line of code.

Why v2?

v1 (CLI-based) v2 (SDK-based)
Backend Cursor Agent CLI subprocess Official cursor-sdk Python library
Auth CURSOR_API_KEY or agent login (no key needed) CURSOR_API_KEY required
Stateful sessions No Yes (X-Cursor-Session-ID)
Thinking/reasoning No Yes (opt-in)
CORS No Yes
Session management API No Yes
Docker Yes Yes

Use v1 if you have a Cursor IDE login but no API key (common in corporate environments where an admin controls access).

Use v2 if you have a Cursor API key and want stateful sessions, thinking support, and a production-ready server.

cursorpipe v2 Architecture

Quick start

Option 1 — pip install (simplest)

# bash / macOS / Linux / WSL
pip install "cursorpipe[server] @ git+https://github.com/Abhi5h3k/cursorpipe.git@v2.0.7#subdirectory=v2"
export CURSOR_API_KEY=crsr_your_key_here
cursorpipe-server

# Windows (PowerShell)
pip install "cursorpipe[server] @ git+https://github.com/Abhi5h3k/cursorpipe.git@v2.0.7#subdirectory=v2"
$env:CURSOR_API_KEY = "crsr_your_key_here"
cursorpipe-server

Server starts on http://localhost:8080.

#subdirectory=v2 tells pip to install from the v2/ folder of this repo. v1 and v2 share the package name cursorpipe — install one or the other, not both.

Option 2 — Docker

2a — Pre-built image (fastest, no clone needed)

# bash / macOS / Linux / WSL
docker run --rm -p 8080:8080 --pull always \
  -e CURSOR_API_KEY=crsr_your_key_here \
  ghcr.io/abhi5h3k/cursorpipe:latest

# Windows (PowerShell)
docker run --rm -p 8080:8080 --pull always `
  -e CURSOR_API_KEY=crsr_your_key_here `
  ghcr.io/abhi5h3k/cursorpipe:latest

Tip: --pull always ensures Docker fetches the latest image before starting.

For multiple settings, use an env file:

# bash / macOS / Linux / WSL
cp v2/.env.example .env
# → fill in CURSOR_API_KEY and any overrides

docker run --rm -p 8080:8080 --pull always --env-file .env \
  ghcr.io/abhi5h3k/cursorpipe:latest

# Windows (PowerShell)
Copy-Item v2\.env.example .env
# → fill in CURSOR_API_KEY and any overrides

docker run --rm -p 8080:8080 --pull always --env-file .env `
  ghcr.io/abhi5h3k/cursorpipe:latest

The image is rebuilt automatically on every push to main.

2b — Build from source

# bash / macOS / Linux / WSL
git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe/v2
cp .env.example .env
# → set CURSOR_API_KEY in .env
docker compose up --build

# Windows (PowerShell)
git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe/v2
cp .env.example .env
# → set CURSOR_API_KEY in .env
docker compose up --build

Option 3 — clone + uv (for development)

# bash / macOS / Linux / WSL
git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe/v2
uv sync --extra server
cp .env.example .env
# → set CURSOR_API_KEY in .env
python -m cursorpipe_server

# Windows (PowerShell)
git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe/v2
# OneDrive: uncomment to avoid hardlink errors
# $env:UV_LINK_MODE = "copy"
uv sync --extra server
Copy-Item .env.example .env
# → set CURSOR_API_KEY in .env
python -m cursorpipe_server

First request

# bash / macOS / Linux / WSL
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"composer-2.5","messages":[{"role":"user","content":"Hello!"}]}'

# Windows (PowerShell)
Invoke-RestMethod http://localhost:8080/v1/chat/completions `
  -Method Post `
  -ContentType "application/json" `
  -Body '{"model":"composer-2.5","messages":[{"role":"user","content":"Hello!"}]}'

# Works with the standard OpenAI SDK — no changes needed
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")
response = client.chat.completions.create(
    model="composer-2.5",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

Features at a glance

  • OpenAI-compatible /v1/chat/completions — works with LangChain, LiteLLM, Open WebUI, and any OpenAI client
  • Streaming — true SSE, token by token
  • Stateless by default — each request is independent; client sends full conversation history
  • Opt-in stateful sessions — add X-Cursor-Session-ID to preserve agent state across turns
  • Session management API — list, create, inspect, and delete sessions via REST
  • Thinking/reasoning content — opt-in reasoning_content exposure (compatible with DeepSeek/o1 clients)
  • CORS — browser clients work out of the box
  • Request tracing — X-Request-ID on every response
  • Structured logging — configurable log level
  • Docker + healthcheck — production-ready from day one

Next steps