Skip to main content
Install the CLI, configure a coding key, and connect a harness. On macOS and Windows 11, Claude Code and Claude Desktop can share the optional on-device proxy; on macOS, Cursor can use it too.

​
Prerequisites

  • One of the supported harnesses installed locally: Claude Code, the Claude Desktop app, Cursor, Codex, Pi, Oh My Pi, or VS Code (via GitHub Copilot Chat).
  • Access to the Valar Dashboard to create a coding key.
  • macOS, Linux, or WSL for the CLI; on Windows 11, Claude Code and Claude Desktop.

​
Install the CLI

Install the valar CLI, a single binary with no runtime dependencies:
On Windows, from PowerShell:
Confirm it is on your path:

​
Create a coding key

In the Valar Dashboard, open ValarCode and create a coding key. Coding keys are scoped to agentic harnesses like Claude Code, Cursor, Codex, and Pi, and they carry your routing split. They use the vlrcode_ prefix, and the token is shown once, so copy it before you leave the page.
A new key works right away. Until you set a split, it routes on Auto — Valar picks the target model — so it is safe to connect before you have tuned anything. See Model routing.
Run valar configure once to store the key locally so you can drop --api-key from later commands:
The key is resolved from, in order: --api-key, then $VALAR_API_KEY, then ~/.valar/config.json, then an interactive prompt.

​
Connect a harness

Connect each harness from your own user account. Choose its guide for setup and restart requirements:

Claude Code

valar claude on

Claude Desktop

valar claude-desktop on

Cursor

valar cursor on

Codex

valar codex on

opencode

valar opencode on

Pi

valar pi on

Oh My Pi

valar ohmypi on

VS Code

valar copilot on
Routing Cursor requires a paid Cursor plan (Pro, Business, or Enterprise) — valar cursor on fails on the free plan or when Cursor is not signed in. valar cursor routes the Cursor editor (the desktop app) on macOS and Linux; it is not available on Windows. On macOS it uses the on-device proxy when one is set up with valar proxy enable (Cursor 3.21.16 or newer); without it, Cursor is connected directly. The Cursor CLI (cursor-agent) is not supported. VS Code routing goes through GitHub Copilot Chat’s custom-endpoint provider, so it needs a signed-in Copilot and a recent VS Code. valar vscode and valar copilot are the same command.

​
On-device proxy

Provision the shared proxy once on macOS or Windows 11, then enable each supported harness. Claude Code and Desktop retain their native login and can use subscription-first routing:
Enable only the apps you use. On macOS, proxy setup requests administrator access. On Windows it needs none; Windows asks you to confirm the local certificate instead. Setup does not turn either app on by itself. Each app has its own ON/OFF control. Without a usable proxy, Claude Code uses direct routing; Desktop uses a direct provider profile when no proxy is provisioned. You can also select direct routing with --direct. See On-device proxy for setup, quota-first, and corporate networks. To deploy with MDM, see Roll out with MDM. The proxy runs on macOS and Windows 11; Claude Code on Linux uses direct routing.

​
Per-engineer attribution

To attribute usage to each engineer, the CLI attaches a client id to every request. Most harnesses (Claude Code, Claude Desktop, Codex, Pi, Oh My Pi, and VS Code/Copilot) send it as an X-Valar-Client-Id header; Cursor, which cannot set custom headers, rides it as a token suffix (<coding-key>~<client-id>). By default the client id is your OS username (normalized to lowercase a-z 0-9 . _ - @ +, capped at 64 characters), so the analytics leaderboard shows real engineers rather than opaque strings. Change how it is derived with --user-id: The chosen id is recorded on on, so you can print it any time:
A plain key with no client id still works, but those requests are not attributed to an engineer. The client id is supplied by the client and is used only for attribution and routing. It is not a security boundary; access is gated on the coding key itself.

​
CLI reference

The CLI follows a harness-first grammar. A bare harness command normally means on, so valar claude is the same as valar claude on. Claude Desktop is the exception: valar claude-desktop prints help; include on, off, or status.
Harness names are claude, claude-desktop, cursor, codex, pi, ohmypi, opencode, and copilot. vscode is an alias for copilot. valar status summarizes them; valar off attempts to turn off all configured harnesses. valar update is an alias for valar upgrade. Per-harness commands Flags

​
Keeping the CLI current

--check reports available updates without installing them or migrating configuration. upgrade verifies the download’s SHA256, replaces the CLI, and completes required configuration and service updates. Run it from your own terminal session, without adding sudo. If migration must refresh running Claude Code sessions, the upgrade asks before interrupting them. Use valar upgrade --force only when that interruption is acceptable. Saved conversations remain available; interrupted requests and tools are not replayed automatically. Follow any instructions to reopen claude agents or resume an interactive conversation. An older socket-based Claude setup moves to the proxy lane when the machine can support it, otherwise to direct routing. A saved quota-first preference remains saved, but direct requests use Valar without the Claude subscription. Installing the proxy is a separate step that may require administrator access on macOS.

​
If an upgrade does not complete

Read the full error to see whether installation failed or the new CLI could not finish updating configuration or services. Keep the recovery records and address the reported cause before retrying. valar upgrade checks for a newer repair first; repeating the same error without a fix will not help. Do not install an older CLI over partially migrated configuration. If you need to stop routing, use the harness’s off command when the CLI says that recovery path is available, and restart affected sessions as instructed. Unknown or unreadable configurations can require repair before OFF is safe.

​
Automatic update notices

Interactive commands can offer an upgrade before continuing; non-interactive commands print a notice. The check is cached for up to a day. Set VALAR_NO_UPDATE_CHECK=1 to disable these notices.

​
Deprecated options

proxy enable --force, --no-restart, and --off are deprecated no-ops with warnings. Use harness commands to change routing and approve session restarts.

​
Managing keys

  • Revoke a coding key from the dashboard at any time. Requests using it stop resolving.
  • Issue a separate key per team or experiment to run different splits side by side. Each key can have its own routing policy.

​
Next steps

Model routing

Set the split and choose target models.

Analytics & savings

Watch usage and savings come in per engineer.