Skip to content

Getting Started

Prerequisites

1. Cursor Agent CLI

Install the Cursor CLI agent (official docs):

curl https://cursor.com/install -fsS | bash

irm 'https://cursor.com/install?win32=true' | iex

The Dockerfile handles installation automatically — skip this step.

Verify it's installed:

agent --version

2. Authentication

Pick one:

agent login

Opens a browser, authenticates with your Cursor account, and stores credentials locally.

Create a key at cursor.com/dashboard/api — see How to create a Cursor API key for a step-by-step walkthrough.

export CURSOR_API_KEY=crsr_your_key_here

$env:CURSOR_API_KEY = "crsr_your_key_here"

set CURSOR_API_KEY=crsr_your_key_here

CURSOR_API_KEY=crsr_your_key_here

Place .env in the directory where you run cursorpipe-server. Both CURSOR_API_KEY and CURSORPIPE_API_KEY are accepted.

Choose your path

The fastest way to get an OpenAI-compatible API running. No Python needed on the host.

git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe
export CURSOR_API_KEY=crsr_your_key_here
docker compose up

git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe
$env:CURSOR_API_KEY = "crsr_your_key_here"
docker compose up

Test it:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-4.5-sonnet-thinking","messages":[{"role":"user","content":"Hello!"}]}'

See Docker for full deployment docs.

Run the OpenAI-compatible server without Docker:

pip install "cursorpipe[server] @ git+https://github.com/Abhi5h3k/cursorpipe.git@v0.1.4"
export CURSOR_API_KEY=crsr_your_key_here
cursorpipe-server

pip install "cursorpipe[server] @ git+https://github.com/Abhi5h3k/cursorpipe.git@v0.1.4"
$env:CURSOR_API_KEY = "crsr_your_key_here"
cursorpipe-server

Server starts on http://localhost:8080. See HTTP Server for full docs.

Install just the library (no server dependencies):

pip install "cursorpipe @ git+https://github.com/Abhi5h3k/cursorpipe.git@v0.1.4"

uv pip install "cursorpipe @ git+https://github.com/Abhi5h3k/cursorpipe.git@v0.1.4"

git clone https://github.com/Abhi5h3k/cursorpipe.git
cd cursorpipe
pip install .

Your first prompt (Python library)

Create a file called hello.py:

import asyncio
from cursorpipe import CursorClient

async def main():
    client = CursorClient()

    response = await client.generate(
        model="claude-4.5-sonnet-thinking",
        prompt="Say hello in a creative way!",
    )
    print(response)

    await client.close()

asyncio.run(main())

Run it:

python hello.py

The first request can take ~14s due to process startup and session creation. Add warmup() at startup to move that cost upfront:

async def main():
    client = CursorClient()
    await client.warmup(pool_size=3)  # pre-start process + pre-create sessions

    # First request is now as fast as subsequent ones (~5s)
    response = await client.generate(
        model="claude-4.5-sonnet-thinking",
        prompt="Say hello in a creative way!",
    )
    print(response)

    await client.close()

Optional: faster JSON parsing

Install the fast extra for ~4.6x faster JSON serialization (uses Rust-backed orjson):

pip install "cursorpipe[fast] @ git+https://github.com/Abhi5h3k/cursorpipe.git@v0.1.4"

That's it! Check out the Examples page for streaming, sessions, framework integration, and more. Or jump to HTTP Server / Docker if you want the language-agnostic API.

Configuration

All behaviour is controlled via environment variables (prefix CURSORPIPE_) or a .env file — including port, timeouts, pool size, and transport strategy. See the full Configuration reference.