Skip to main content
Valar routes Claude Desktop’s Code and local Cowork tabs on macOS, and its Code tab on Windows 11. Local Cowork on Windows is not supported yet. The app and the Claude Code CLI are configured and reported separately. You need Claude Desktop, the Valar CLI, and a coding key.

​
Choose a routing method

valar claude-desktop on selects the proxy lane when the proxy is provisioned; otherwise it uses the direct lane. Pass --direct to explicitly choose the provider profile.

​
On-device proxy

Provision the shared component once, then enable Desktop:
See On-device proxy for setup, certificates, network policies, logs, and removal. To deploy with MDM, see Roll out with MDM. Turning Desktop OFF does not turn Claude Code OFF. Once Desktop’s proxy arrangement is established, ordinary ON/OFF toggles do not restart the app.

​
Direct lane

Direct routing sends inference to Valar without using your Claude subscription. The app reads its provider profile at startup, so changing to or from this lane may require a restart. To include the Chat tab:
Pass --with-chat on each on that should include Chat. The direct profile has its own chat history; it does not merge with your claude.ai history when you switch lanes.

​
Switch lanes and running sessions

You can switch directly between lanes:
When a running app needs to restart, Valar explains the change and asks:
  • No: routing and the running app remain unchanged.
  • Yes: Valar quits the app, applies the change, and reopens it. On Windows, Claude Desktop stays in the notification area after its windows close, so Valar ends the app a few seconds after asking it to close.
  • --force: approve that restart without a prompt, for example valar claude-desktop on --direct --force.
If the app cannot quit, Valar leaves its configuration unchanged. If it cannot reopen, Valar asks you to open it manually. Saved history remains in its original mode; active requests and tasks may be interrupted. First-time proxy activation and changes to proxy connection settings or certificates may require a restart. Established proxy ON/OFF toggles do not, including when --force is supplied.

​
History and MCP servers on the direct lane

On the proxy lane, Claude Desktop keeps its normal history and MCP servers unchanged. The direct lane runs the app in a separate provider profile. When you switch lanes, Valar copies your local Code sessions (and local Cowork sessions on macOS) and scheduled tasks between the two, and never deletes a session. It also adds your local MCP servers to the direct-lane profile each time you turn the direct lane on. Chat history is stored by Claude and is not affected. To distribute a fixed list of servers for the direct lane, place a JSON array at ~/.valar/claude/desktop-mcp.json (%USERPROFILE%\.valar\claude\desktop-mcp.json on Windows), in the schema Claude Desktop uses for managed MCP servers (name, transport, then command/args/env or url/headers). An entry there replaces any server with the same name. The file is read whenever Valar writes the profile; a file that is not valid JSON stops the command with an error rather than being skipped.

​
Check routing

Status reports OFF or the active lane. On the proxy lane it also reports service health, certificate information, and forwarding activity. To check Valar forwarding, send a Code or local Cowork request that uses Valar, then run:
The check exits nonzero until the proxy observes a Desktop request successfully forwarded to Valar after routing was enabled. A subscription-served request does not satisfy it. See Status and logs.

​
Quota-first: use your own subscription first

With Desktop on the proxy lane and signed into an eligible Claude account:
Quota-first uses included subscription allowance before Valar. The preference is shared with Claude Code, but each app’s requests identify the account they use. See the shared Claude quota-first controls for limits, counters, reset, and opt-out. The direct lane cannot use quota-first. Desktop Chat and cloud Cowork sessions are outside the proxy integration’s coverage.

​
Turn off routing

On the proxy lane, new connections pass through to Anthropic without decryption. The shared proxy remains installed. On the direct lane, Valar removes its profile or restores the configuration it replaced, with a restart when required. To uninstall the shared services and their machine settings, first turn off every harness using them, then follow Remove the proxy.

​
Provider profile details

The direct lane writes a Valar profile to Claude Desktop’s provider-profile folder:It records the Valar endpoint, coding key, model list, and request-attribution headers.The pre-enable profile configuration is backed up at ~/.valar/claude/desktop-backup.json (%USERPROFILE%\.valar\claude\desktop-backup.json on Windows). OFF restores that configuration; it removes the configuration tree if Valar created it.
Open a separate direct-routed instance:
It uses ~/.valar/claude/desktop-session-3p (%USERPROFILE%\.valar\claude\desktop-session-windows\Claude-3p on Windows) and keeps its history there. Your main app’s configuration, login, and reported routing stay unchanged.Only one such instance runs at a time. Add --force to replace an existing instance. Explicit --direct allows this mode even when the shared proxy is provisioned.

​
Security and machine changes

Certificate trust, shared proxy services, and corporate network controls are documented under On-device proxy.

​
Collect CLI logs for support

Inspect ~/.valar/cli.log for command/setup failures and valar proxy logs for proxy traffic diagnostics. See Support logs for collection, redaction and rotated history. Review logs before sharing them.

​
Next steps

On-device proxy

Shared setup, certificates, and network policies.

Claude Code

Configure the terminal CLI separately.