cursor-byok: a local model gateway for Cursor's Agent, reviewed

What cursor-byok actually replaces

Cursor ships with a fixed set of model channels, and the billing and subscription that come with them. The README frames the project's reason for existing in exactly those terms: many Agent products "bundle their tool capabilities with a fixed set of models, subscriptions, and billing options." cursor-byok inserts a local service between the Cursor client and whatever model API you already pay for, so the Agent loop keeps working while the model behind it changes.

The audience is narrow and specific. You need an OpenAI- or Anthropic-compatible endpoint, credentials for it, and a reason to prefer it over what Cursor offers by default: existing credits, a self-hosted model, a regional provider, or a model ID the platform does not list. If none of those apply, the project adds a process to your machine and nothing else.

The README is explicit that this is unofficial. It states the project "is not affiliated with or endorsed by Cursor or its developers." That is not a formality. It means a Cursor change to the wire protocol can break the gateway, and the fix depends on this repository's maintainers noticing.

The data flow: Cursor client, local service, your provider

The README's diagram is short and worth reading literally. Cursor sends Agent requests and tool results to the cursor-byok local service. The service forwards them as OpenAI- or Anthropic-compatible requests to the model API you configured. Responses come back the same way.

What the service owns is the part that would otherwise break: protocol adaptation between Cursor's request shape and your provider's, model request forwarding, tool-call coordination, and conversation state. That last item matters most. Agent workflows are multi-turn and interleave tool results with model output, so a gateway that only proxied single completions would not preserve tool calling, Skills or MCP. The README lists all three as features that survive the routing.

Configuration lives per model channel. Each one can define its own context window, maximum output tokens, reasoning effort, custom headers and additional request parameters, and each can be OpenAI-protocol or Anthropic-protocol. Two protocols and a custom endpoint is the full menu.

The repository layout backs this up. There is a server/ directory, an apps/desktop Tauri app, a crates/semble-core crate, a protocols/cursor/ directory, and a support/benchmarks/semble member in the Cargo workspace. The Dockerfile copies protocols/cursor/ into the server build stage, which is consistent with the protocol handling being a first-class part of the server rather than glue in the UI.

Installing cursor-byok and running a first request

The README's Quick Start points at GitHub Releases for a platform build, and the project publishes macOS, Windows and Linux builds. Download the latest release for your platform and launch it. There is no package manager install documented in the README.

If you would rather run the server yourself, the Makefile exposes a development target that expects a built web console. Build the console first, then start the server with the console directory pointed at the build output:

make build-web
make dev-server

The server reads CURSOR_CONSOLE_DIR from the environment when started this way. The Dockerfile sets a different default for container runs, CURSOR_LISTEN_ADDR=0.0.0.0:3000, and the Makefile's build-docker target builds the image under the tag cursor-byok:local:

make build-docker

The container image runs the server as an unprivileged user and keeps its data under /data, which the Dockerfile creates and chowns to that user. Port 3000 is the listen address the image sets.

Once the dashboard is up, open Model Settings and enter the endpoint, API key and model ID. Test the configuration. The README says to return to the dashboard and start the service after a test passes. Then quit Cursor completely, restart it, start a new conversation and select the configured model. The README repeats the test-then-start step twice in the Quick Start, which reads like an editing slip rather than two distinct steps; treat it as one.

The restart instruction is not optional. The README ties it to two cases: after upgrading Cursor, and after configuring a model for the first time.

Where the local gateway model breaks down

The most consequential limitation is stated plainly in the README: "API keys and application settings are stored locally; requests are still sent to the model provider you configure." Local storage of credentials is not the same as local inference. Your prompts, code context and tool results leave the machine on every turn, bound for whichever endpoint you typed into Model Settings. Anyone adopting this for data-residency reasons should read that sentence twice.

The second limitation is compatibility surface. cursor-byok speaks OpenAI- and Anthropic-compatible protocols. A provider with a materially different request or response shape, or a tool-calling format that diverges from those two, is outside what the README claims. There is a custom endpoint option, but the README does not document what a custom endpoint must implement, so the burden of figuring that out falls on you.

Third, the project is tied to Cursor's client behaviour and Cursor is not a party to it. The README's own restart-after-upgrade instruction is an admission that the integration is version-sensitive. Nothing in the README documents rollback, a compatibility matrix, or a supported Cursor version range.

Finally, the model APIs you connect bill you directly. The README puts this in an admonition: the project is free and open source, but "the model APIs you connect may charge for usage." Self-hosting the gateway does not make inference free.

How it compares with routing through a hosted aggregator

The obvious alternative is a hosted aggregator such as OpenRouter: you point Cursor at a remote gateway, and it fans out to many providers behind one key. The difference in approach is where the routing logic and the credentials live. With an aggregator, a third party holds the key, sees the traffic, and owns uptime. With cursor-byok, the routing process runs on your machine and the keys stay in local storage, but the requests still terminate at the provider you chose.

That trade cuts both ways. A local gateway gives you per-channel control that a hosted aggregator rarely exposes: context window, maximum output tokens, reasoning effort, custom headers and extra request parameters, set independently for each model channel. It also gives you connection benchmarks that report time to first token and generation speed, plus raw provider responses for inspection. Those are diagnostic tools for the moment a channel misbehaves.

The cost is operational. You run a process, you keep it current with releases, and you own the failure when Cursor's client changes. An aggregator absorbs that work and charges for it. The README's Roadmap section says the project will keep working on model compatibility, Agent tooling, local runtime stability and the self-hosting experience, with plans tracked in a GitHub Discussions thread. That is a statement of direction, not a commitment to a date.

Maintenance, licence and what a release cadence implies

cursor-byok is MIT licensed, and the README states the project is free and open source. MIT is permissive: it allows commercial use, modification and redistribution, and it comes with no warranty. The licence covers the code in this repository. It does not cover the model APIs you connect, which have their own terms, and it does not cover Cursor itself. Nothing here is legal advice; read the LICENSE file and your providers' terms.

The repository is not archived, and the last push was on 2026-09-20. Releases are recent and closely spaced: v1.0.0 on 2026-09-15, v1.0.1 on 2026-09-20, with v0.1.7 on 2026-09-04 before that. A 1.0 line reached within roughly two weeks of the 0.1.x series suggests the API surface is settling, but the version numbers alone do not tell you how much churn to expect in the protocol layer.

Upgrade cost is the part to plan for. The README instructs a full Cursor restart after upgrading Cursor and after first configuring a model, which means the gateway and the client have to be brought up in a known order. There is no documented rollback procedure and no compatibility matrix, so a failed upgrade leaves you reconstructing the previous state from the releases page. Building from source is supported through the Makefile and the Cargo workspace, and the Dockerfile gives a reproducible server image if you want to pin a build rather than track releases.

Editorial conclusion

Adopt cursor-byok if you already hold API credits or a self-hosted endpoint and want Cursor's Agent to run against them, and if you accept that requests leave your machine for whichever provider you configure. Do not adopt it if you need a hosted, managed routing layer or a published security model for the local service. Before committing, verify that your provider is OpenAI- or Anthropic-compatible, that your model ID accepts the context window and output limit you set, and that the Cursor version you run is the one named in the release you download.

Frequently asked questions

Official sources

1. Issues
2. leookun/cursor-byok on GitHub
3. License: MIT
4. README
5. Releases