Skip to main content
ValarCode puts Valar’s models in Cursor’s model picker. On macOS with the on-device proxy, it also answers Cursor’s Auto with Valar Auto. See Set up ValarCode for the shared setup and the client-id model. valar cursor runs on macOS and Linux. It is not available on Windows.

​
Prerequisites

  • Cursor installed and signed in, on a paid plan (Pro, Business, or Enterprise). valar cursor on fails on the free plan or when Cursor is not signed in.
  • For the on-device proxy, Cursor 3.21.16 or newer. With an older Cursor and the proxy set up, valar cursor on warns in side by side, and Valar only stops until Cursor is updated. Without the proxy, any Cursor version works as before.
  • A Valar coding key (vlrcode_…) and the valar CLI (install).
  • On macOS, the on-device proxy is recommended: run valar proxy enable once. Without it, Cursor’s own models such as Composer don’t work next to Valar’s, and Valar only can be worked around. If you set up the proxy before Cursor support, run it again so its certificate covers Cursor. If your organization supplies the proxy certificate, it must also cover Cursor’s servers; see Organization-managed certificates.
  • If your Cursor team settings control custom API keys, keep them allowed. Valar’s key is saved in Cursor as one.

​
Two modes

valar cursor on also turns off the personal API keys saved in Cursor, and valar cursor off turns them back on. If your admin turned on Show serving model name in the response body (details), an answer that Valar Auto picked ends with a short [served by <model>] line. This table describes macOS with the on-device proxy. Without it, see the proxy lane and the direct lane.

​
Enable routing

Quit Cursor first, or let valar do it for you. Cursor keeps its settings in memory and writes them on exit, so a change made while it runs would be undone. Run once for each user account:
If Cursor is running, valar offers to quit it, apply the change, and reopen it. Pass --force to pre-answer that prompt; scripts and MDM need it, since a non-interactive run fails rather than ask. Valar only is sticky: a later valar cursor on keeps it. Run valar cursor on --valar-only=false to go back to side by side. valar cursor off also clears it.

​
The proxy lane and the direct lane

On macOS, Cursor’s chat goes through the on-device proxy (the proxy lane). The proxy is what lets Cursor’s own models keep working side by side, and what makes Valar only hold: it checks each message, switches a pick of one of Cursor’s models to Valar Auto, and blocks what it cannot keep on Valar. Without the proxy, Cursor uses the direct lane: Valar is Cursor’s OpenAI endpoint, and nothing checks messages on the way. In Valar only, a check inside Cursor blocks a send on one of Cursor’s own models with '<model>' is not routed through Valar. Select a valar- model from the picker. The direct lane is the only lane on Linux. Check the lane and state any time:
status shows on, proxy lane or on, direct lane, whether Valar only is on, and a fix when something needs one. partial means one of Valar’s settings was turned off inside Cursor. Signing out of Cursor does this. Run the valar cursor on command that status prints.

​
When Cursor says “Message not sent”

On the proxy lane, a blocked message shows Cursor’s own Message not sent box with a short message saying why and what to do:
If the proxy is stopped, Cursor’s chat stops too (“Reconnecting…”). valar cursor status names the fix, usually valar proxy restart.

​
What gets written

Cursor stores its settings in a SQLite database, state.vscdb, and in settings.json. valar cursor on sets: On the proxy lane, Cursor’s Auto is selected; on the direct lane, valar-auto is. Existing chats are switched too. In Valar only on the direct lane, valar cursor on also adds a check to ~/.cursor/hooks.json. Before the first change, the touched rows and settings.json are snapshotted under ~/.valar/cursor/ (keyed by a hash of each file’s path, so separate installs never collide). off restores them. Changes you made to settings.json after that are kept. Cursor’s settings stored in state.vscdb, including model toggles and models you added, go back to how they were before valar cursor on.
Cursor cannot set custom request headers, so the client id rides as a token suffix (<coding-key>~<client-id>) rather than an X-Valar-Client-Id header. The gateway splits on the last ~, authenticates the base key, and routes on the id. By default the id is your OS username; use --user-id RANDOM for an opaque one. See per-engineer attribution.
Cursor keeps state.vscdb values as SQLite TEXT and silently discards any row whose value is a BLOB on launch. The CLI writes the values as TEXT for this reason; a raw byte write would be wiped on the next restart.

​
Limits

  • Valar only covers chat. Cursor’s Agent Review (Bugbot) still runs on Cursor’s models; turn it off in your Cursor team settings if you need everything on Valar. Chat titles are also named by Cursor’s own model, and Tab completions always run on Cursor’s models.
  • Claude models inside Cursor are not served by Valar. In Valar only they are not offered.
  • valar cursor routes the Cursor editor (the desktop app). The Cursor CLI (cursor-agent) is not supported.
  • Behind a company VPN or proxy, set up the Valar proxy to go through it: valar proxy enable --upstream-proxy <address>. See Corporate networks.

​
Turn off routing

Quit Cursor first (or pass --force), then:
This puts back what valar cursor on changed and turns Valar only off. Start Cursor again to pick up the change. The proxy stays installed for other tools; valar proxy disable removes it once nothing uses it.

​
Next steps

Model routing

How cohorts and the split decide which model serves each request.

Models

The open-weight targets and the frontier Claude tiers.