How to Integrate FreeLLMAPI with Cursor and Continue Clients: A Complete Setup Guide

You can integrate FreeLLMAPI with Cursor and Continue by configuring their OpenAI-compatible settings to point at your local proxy server (http://localhost:3001/v1) using a unified API key, with Cursor requiring a public tunnel for cloud access.

FreeLLMAPI is an OpenAI-compatible proxy server that unifies access to multiple LLM providers through a single local endpoint. Both Cursor and Continue can consume its services natively, though each requires slightly different configuration due to their architectural differences. This guide walks through the complete setup using source code references from tashfeenahmed/freellmaapi.

Architecture Overview

Understanding how each component interacts helps explain the configuration differences.

Component	Role	Interaction
FreeLLMAPI server (server/src/app.ts)	Exposes OpenAI-compatible endpoints (/v1/chat/completions, /v1/completions, etc.)	Receives HTTP requests from clients, forwards them to upstream providers, returns responses
Cursor	Cloud-hosted editor requiring public URL access	Needs tunnel (ngrok) to reach localhost; sends requests to public URL
Continue	Local editor extension	Can call http://localhost:3001/v1 directly
Unified API key	Stored in SQLite DB, exposed via Authorization: Bearer <key>	Used by both clients; Cursor can alternatively use revocable URL tokens

The server distinguishes between the root (http://localhost:3001) used by Claude Code and the /v1 path required by all other OpenAI-compatible clients, as documented in docs/clients.md (lines 56-60).

Step 1: Start the FreeLLMAPI Server

Clone and launch the proxy server from the repository root:

npm install
npm run start   # defaults to http://localhost:3001

On first run, the server logs a setup code to the console. The unified API key appears in the dashboard UI at http://localhost:5173.

The server initialization logic resides in server/src/app.ts, where Express routes for /v1/*, /mcp, and other endpoints are configured along with the required middleware.

Step 2: Obtain Your Unified API Key

Navigate to the dashboard to retrieve your credentials:

1. Open http://localhost:5173
2. Go to Keys → Agents
3. Copy the unified key

This key works across all integrated clients and is validated against the SQLite database on each request.

Step 3: Configure Continue for Local Usage

Continue can connect directly to localhost since it runs as a local extension. Add this configuration to your Continue config file (typically ~/.continue/config.yaml):

models:
  - name: FreeLLMAPI Chat
    provider: openai
    model: auto                # selects best model from live catalog

    apiBase: http://localhost:3001/v1
    apiKey: <unified-key>
    useLegacyCompletionsEndpoint: true   # optional, for autocomplete

Continue now routes all chat and completion requests through FreeLLMAPI, as referenced in docs/clients.md (lines 42-45). The useLegacyCompletionsEndpoint flag enables streaming autocomplete suggestions via the older completions API.

Step 4: Configure Cursor with a Public Tunnel

Cursor runs in the cloud and cannot reach localhost. You must expose your proxy publicly.

4a. Create a Secure Tunnel

Use ngrok or a similar service:

ngrok http 3001

# Output: https://abcd1234.ngrok.io

Copy the HTTPS URL for the next step.

4b. Set Cursor's OpenAI Base URL

In Cursor's settings:

1. Navigate to Settings → Models
2. Find Override OpenAI Base URL
3. Enter: https://abcd1234.ngrok.io/v1

4c. Provide the API Key

In the same settings panel, paste your unified key. Cursor sends this in the Authorization header with each request.

Alternative: URL Token for Header-Injected Requests

If Cursor cannot set custom headers, generate a revocable URL token in the dashboard. Use the tokenized endpoint format instead, as documented in docs/clients.md (lines 52-60). This embeds authentication directly in the URL path.

Step 5: Verify Your FreeLLMAPI Integration

Test both clients to confirm end-to-end functionality.

Test Continue

Run a CLI chat command:

continue chat "Hello, free LLM API!"

Check the response sources to confirm routing through your local proxy.

Test Cursor

Open any file in Cursor and submit a chat prompt. Monitor:

• The ngrok inspector (http://localhost:4040) for incoming requests
• The FreeLLMAPI server logs for forwarded requests and provider selection

Successful responses confirm the proxy is selecting models from the live catalog and returning provider responses.

Key Implementation Files

File	Purpose
server/src/app.ts	Express server setup with /v1/* and /mcp routes
server/src/routes/proxy.ts	Core OpenAI-compatible proxy forwarding logic
server/src/routes/mcp.ts	MCP introspection endpoint for agent discovery
cli/src/tools.ts	setup-cursor command with tunneling instructions
docs/clients.md	Official client integration documentation

These files demonstrate how FreeLLMAPI implements the OpenAI API specification in server/src/routes/proxy.ts, handles authentication middleware, and provides the model catalog aggregation that makes unified access possible.

Troubleshooting Common Issues

• Cursor connection failures: Verify your ngrok URL uses HTTPS and ends with /v1, not the root path
• Continue timeout errors: Check that apiBase includes the /v1 suffix; the root path behaves differently
• Authentication errors: Ensure the unified key is copied exactly from Keys → Agents, not the dashboard session key
• Model not found: Set model: auto or specify an exact model ID from your configured providers

Summary

• FreeLLMAPI exposes OpenAI-compatible endpoints at http://localhost:3001/v1 via server/src/app.ts
• Continue connects directly to localhost with standard API key authentication
• Cursor requires a public tunnel (ngrok) to reach the local proxy
• Both clients use the unified API key from the dashboard, with URL tokens as a fallback
• The /v1 path prefix is mandatory for all non-Claude-Code clients

Frequently Asked Questions

Can I use FreeLLMAPI with other OpenAI-compatible clients besides Cursor and Continue?

Yes. Any client supporting custom apiBase and apiKey configuration can integrate with FreeLLMAPI. The proxy implements standard OpenAI endpoints in server/src/routes/proxy.ts, including /v1/chat/completions and /v1/completions. Configure the base URL to your proxy address (public for cloud clients, localhost for local tools) and supply the unified key in the Authorization header.

Why does Cursor require a tunnel while Continue works with localhost?

Cursor's editor interface runs in the cloud, not on your local machine, so its servers cannot reach localhost:3001. Continue operates as a local VS Code extension or standalone application, making direct localhost connections possible without additional networking configuration.

How do I regenerate or revoke API keys?

Open the dashboard at http://localhost:5173, navigate to Keys → Agents, and use the rotation controls. The unified key can be regenerated instantly. For URL-based tokens used with Cursor, each token shows a revoke option that immediately invalidates that specific credential without affecting others.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}