Cursor Integration

Cursor is an AI-first code editor built on a VS Code fork. It provides intelligent code completion (Tab), chat assistance (Cmd+L), Composer for multi-file editing (Cmd+I), and an Agent mode that can plan and execute multi-step coding tasks. AVELIN works as a drop-in backend for both Cursor's OpenAI and Anthropic wire formats.

Why AVELIN + Cursor? Cursor's Agent mode shines with large context and fast throughput — AVELIN delivers 1M-token context windows, ~100 tps on avelin-coding-pro, and automatic provider failover. You get frontier-tier coding quality without Cursor's usage caps.

Quick Setup (3 minutes)

Step 1: Get your AVELIN API key

Sign up at avelin.ai and generate an API key. It looks like sk-avelin-....

Step 2: Open Cursor Settings

1. Open Cursor

2. Click the gear icon (top right) → Cursor Settings

3. Click Models in the left sidebar

   Or press Cmd+Shift+J (Mac) / Ctrl+Shift+J (Windows) to jump straight to Models.

Step 3: Configure the Anthropic endpoint (RECOMMENDED)

We strongly recommend the Anthropic endpoint — it gives you structured thinking blocks, better streaming, and the full Agent mode experience.

In the Models panel:

1. Anthropic API Key → paste your key: sk-avelin-...
2. Toggle on Override Anthropic Base URL
3. Set it to: https://api.avelin.ai ← no /v1 suffix for Anthropic

Step 3 (alternative): Configure the OpenAI endpoint

Use this if a specific Cursor feature requires OpenAI-format responses (rare).

1. OpenAI API Key → paste your key: sk-avelin-...
2. Toggle on Override OpenAI Base URL
3. Set it to: https://api.avelin.ai/v1 ← includes /v1 for OpenAI

⚠️ Do NOT enable both overrides simultaneously. If you use Anthropic, turn OFF the OpenAI override — otherwise Cursor routes Anthropic-model requests to the OpenAI endpoint and you'll get 404s. (Source: Cursor forum thread #144899)

Step 4: Select a model

1. Open the chat panel (Cmd+L)
2. Click the model dropdown at the top
3. Disable Auto
4. Type or select: avelin-coding-pro

Cursor will remember this model for future sessions.

Step 5: Verify it works

Type in the chat:

What model are you and what's your context window?

A correct response will:

• Identify as an AVELIN model (e.g. avelin-coding-pro)
• Stream token-by-token without hanging
• Show reasoning content if you ask a complex question

If it errors, see Troubleshooting below.

Why Anthropic Endpoint is Recommended

Cursor was designed with Anthropic's API as its primary backend. The Anthropic endpoint on AVELIN matches that expectation exactly.

Available AVELIN Models

Coding Models (1M context)

General Models (256K context)

Agentic Models (256K context)

Recommended Models by Cursor Feature

Cursor Features with AVELIN

Tab Autocomplete

Tab completion fires on every keystroke. Use avelin-fast for lowest latency:

1. Switch model to avelin-fast in the dropdown
2. Start typing — Cursor will suggest completions inline
3. Press Tab to accept

Tip: You can set a separate model for Tab in Cursor Settings → Models → Tab Model (if your Cursor version supports it).

Chat (Cmd+L)

Use @ mentions to include context:

@file:src/auth.py Review this for security issues
@folder:src/ Summarize the architecture
@codebase How does the payment flow work?
@web Search for the latest FastAPI security advisories

Composer (Cmd+I)

Composer edits multiple files in one shot. Select files with @file: and describe the change:

@file:user_service.py @file:user_repository.py @file:user_controller.py
Refactor to use the repository pattern. Add proper error handling.

Composer will show a diff preview — accept or reject each change.

Agent Mode (Cmd+I → Agent tab)

Agent mode is Cursor's autonomous coding mode. It can:

• Read and write files
• Run terminal commands
• Search the web
• Iterate until the task is done

Best model for Agent mode: avelin-agentic-ultra — it's purpose-built for multi-step tool calling.

Example prompt:

Set up a FastAPI project with:
- User registration and login endpoints
- JWT authentication middleware
- SQLAlchemy models
- pytest tests for all endpoints

Agent will plan, create files, run tests, and fix issues until everything passes.

Custom Instructions

Add project-level rules that apply to every chat:

1. Create .cursorrules in your project root:

You are working on a Python FastAPI backend.
- Use async/await for all endpoints
- Use Pydantic v2 for data validation
- Follow PEP 8, line length 100
- Write tests with pytest and httpx
- Use repository pattern for database access

Cursor reads this file automatically — no settings change needed.

HTTP Compatibility (Important!)

If you see connection errors with custom endpoints:

1. Go to Cursor Settings → Network (or General)
2. Find HTTP Compatibility Mode
3. Switch to HTTP/1.1

Custom endpoints (including AVELIN) often don't work well with HTTP/2. This is a known Cursor quirk. (Source)

Verification Checklist

After setup, run through these checks:

• Chat responds: Type "hello" in Cmd+L → get a reply within 5 seconds
• Streaming works: Tokens appear one by one, not in a single chunk
• Thinking works: Ask a hard question → see reasoning before the answer
• Tab works: Type code → get inline completions
• Composer works: Select a file, Cmd+I, ask to add a function → see diff preview
• Agent mode works: Cmd+I → Agent tab → give a multi-step task → Agent executes it

If any check fails, see Troubleshooting.

Performance Tips

Speed

• Use avelin-fast for Tab autocomplete — lowest latency
• Use avelin-coding-pro for chat — best speed/quality tradeoff
• Use avelin-agentic-ultra only for Agent mode — it's slower but more capable

Cost

• Tab autocomplete fires constantly — use avelin-fast to keep costs low
• Chat and Composer are less frequent — use avelin-coding-pro for quality
• AVELIN's prompt caching cuts repeated system prompt costs by ~80%

Context

• AVELIN's 1M context means you can include entire codebases with @codebase
• For very large repos, use .cursorignore (gitignore syntax) to exclude noise:

  node_modules/
  dist/
  vendor/
  __pycache__/
  *.min.js
  

Troubleshooting

"Model not found" or "Invalid model"

Cause: You're using Auto mode, which only works with Cursor's built-in models.

Fix:

1. Click the model dropdown in the chat panel
2. Disable Auto
3. Select an AVELIN model from the list (or type the name)

"API key invalid" or 401 error

Fix:

1. Verify key starts with sk-avelin-
2. Check the base URL:
   • Anthropic: https://api.avelin.ai (no /v1)
   • OpenAI: https://api.avelin.ai/v1
3. Re-paste the key — sometimes copy-paste adds whitespace

404 "Not Found" on Anthropic models

Cause: You have the OpenAI override enabled while using Anthropic models.

Fix: Turn OFF "Override OpenAI Base URL" when using Anthropic models. Only one override should be active at a time.

Connection timeout or slow response

Fix:

1. Switch HTTP mode to HTTP/1.1: Cursor Settings → Network → HTTP Compatibility Mode
2. Try a different model: avelin-fast for speed
3. Check your internet connection to api.avelin.ai:

   curl -I https://api.avelin.ai/v1/models

Tab autocomplete not working

Fix:

1. Make sure a model is selected (not Auto)
2. Use avelin-fast for Tab — it has the lowest latency
3. Check Cursor Settings → Features → Tab is enabled
4. Verify the file type is supported (most are)

Composer shows no changes / empty diff

Fix:

1. Switch to avelin-coding-pro — smaller models may not generate valid diffs
2. Make sure files are saved before Composer runs
3. Try a more specific instruction (e.g. "Add error handling to the processPayment function" instead of "improve this code")

Agent mode loops or fails

Fix:

1. Use avelin-agentic-ultra — it's built for this
2. Break the task into smaller steps
3. Add constraints: "Don't modify files in tests/" or "Use existing patterns in the codebase"

"Cannot invoke added model" / feature locked

Cause: Cursor Free plan doesn't support BYOK models.

Fix: Upgrade to Cursor Pro or Business to use your own API keys.

Example Workflow: Feature Development

1. Cmd+L (Chat): "Plan a REST API for a task tracker with users, projects, and tasks"
   → Uses avelin-coding-pro, returns architecture plan

2. Cmd+I (Composer Agent): "Implement the plan. Create FastAPI app with SQLAlchemy models,
   Pydantic schemas, and CRUD endpoints. Include auth."
   → Uses avelin-agentic-ultra, creates 8 files, runs tests

3. Cmd+L (Chat): "@file:main.py @file:models.py Review for security issues"
   → Uses avelin-coding-pro, finds 3 issues, suggests fixes

4. Tab autocomplete while fixing issues → uses avelin-fast

5. Cmd+I (Composer): "Add comprehensive tests for all endpoints"
   → Uses avelin-coding-pro, generates test file with 40+ tests

Related

• API Quickstart — First API call in 5 minutes
• Cline Guide — VS Code extension alternative
• Continue Guide — Open-source VS Code/JetBrains alternative
• Hermes Agent Guide — Terminal-based coding tool
• Model Catalog — Full model comparison
• Cursor Docs — Official Cursor documentation