Skip to main content
ValarCode puts Valar’s models in Cursor’s model picker. With the on-device proxy (macOS, Windows and Linux), 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, Windows and Linux. On Windows, Cursor always goes through the on-device proxy, in both modes, and there is no --direct.

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 (macOS and Linux), any Cursor version works as before. Windows always uses the proxy, so this always applies there.
  • 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.
  • On Linux, the on-device proxy is recommended, as on macOS. Setting it up asks for administrator access once, to add its certificate to the system certificate store, which Cursor’s chat reads. Cursor also needs the certificate in your NSS database (~/.pki/nssdb), which needs certutil: install libnss3-tools on Debian and Ubuntu, nss-tools on Fedora and RHEL, or nss on Arch, then run valar proxy enable again. Without it, valar cursor on names the package to install. Inside WSL, cursor is the Windows app; set it up from Windows.
  • On Windows, the on-device proxy is required: run valar proxy enable first. Until the proxy is set up and running, valar cursor on stops without changing Cursor and prints the fix. A certificate your organization supplies must also cover Cursor’s servers.
  • 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 line naming the strategy and the model, such as [served by auto-balanced: GLM-5.3 Fast]. This table describes macOS, Windows and Linux 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. On Windows, valar asks each Cursor window to close, as clicking X does, and never ends Cursor by force. If Cursor asks whether to stop agents that are still working, answer it in Cursor: valar waits 20 seconds, then stops without changing anything. If your account has Cursor open in another Windows sign-in (for example over remote desktop), close it there first. 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, Windows and Linux, 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. Windows has no direct lane. 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.

Reasoning levels

On the proxy lane, Valar’s models that offer reasoning levels show Cursor’s Reasoning menu. The level you pick is used for that message. Each model starts on its default level, so nothing changes until you pick another one. Other models show no menu and use a default level. Your organization’s routing can show fewer levels: the menu only offers a level your organization’s routing serves as you picked it. The menu appears after valar upgrade (version 1.1.6 or newer) or valar models refresh. Cursor shows it within a few minutes, or right away after you restart Cursor. On the direct lane there is no menu.

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. On Windows both are under %APPDATA%\Cursor\User. 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 (macOS and Linux), 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/. 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. Valar reads the client id from that suffix. By default the id is your OS username; use --user-id RANDOM for an opaque one. See per-engineer attribution.

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.
  • Cursor’s /summarize (also /compact) is answered by Cursor’s own summarizer in both modes. Cursor sends that command without an API key, so it does not reach Valar.
  • Without the on-device proxy (the direct lane), Valar’s models show no Reasoning menu. Valar uses a default level for each model instead.
  • 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.