valar on engineers’ Macs and Windows 11 PCs, set it up, and keep it current without anyone typing a command. This page explains how valar runs under MDM and in what order to deploy it. On macOS and Linux from a root script, and on Windows from a script run as SYSTEM or as the signed-in user, one command can run most of the setup with valar setup. The sections before Windows describe macOS. Linux fleets are covered in Linux.
How valar runs under MDM
MDM scripts run as root, in the background, with no terminal.valar is built for a signed-in engineer, so three rules follow.
Every command acts for one user. valar changes that user’s configuration in ~/.valar, each app’s settings in the user’s home, and the proxy services that run in the user’s login session. A command run as root with no user selected is refused (V1A-1004). A command acts for the user in one of two ways:
- Proxy setup runs as root, for a selected user.
valar proxy enableneeds administrator access: it sets the network proxy and installs the proxy services. Run it from a root policy withVALAR_USERset to the target account.valardoes the user’s part of the setup as that user.SUDO_USERis read the same way whenVALAR_USERis not set. - Everything else runs as the user.
valar configure,valar upgrade, andvalar <harness> on|offneed no administrator access. Run them as the signed-in user, either through your MDM’s option to run as the signed-in user or by switching to that user from a root script (see the example). Runvalar upgradethis way, not throughSUDO_USER.
valar asks before it restarts a running app. Under MDM it cannot ask, so pass --force (see Restarts).
Choose a lane
The on-device proxy is optional. Without it,valar <harness> on uses the direct lane. The proxy lane adds quota-first and Remote Control. For Cursor on macOS and Linux, it keeps Cursor’s own models working next to Valar’s and makes Valar only strict. It needs two things on every Mac:
- A root certificate your MDM trusts. See Set up the proxy from a root policy.
- Each engineer signed in to Claude Code with their Claude account. Without it, Claude Code stops at “Not logged in”.
Set up with one command
valar setup sets up the proxy and quota-first as your organization’s settings say, and turns on the tools you name. See Set up in one command. On macOS:
VALAR_USER, list claude,cursor (Claude Desktop is not supported there), and bring your organization’s certificate as Linux describes.
- Set
VALAR_USERto the person to set up. Without it, setup refuses (V1A-1004) and changes nothing. - Install
valarwhere only root can write, such as/usr/local/bin: the file and every folder above it must be owned by root, whichls -ld /usr/local/binshows. On Intel Macs, Homebrew makes the admin its owner. When your MDM installs a new release, run the script again. - Provide a coding key as
VALAR_API_KEYthrough a protected channel, or store it first withvalar configure --api-key <key>as the user. Keep keys out of script arguments and logs. - Pass
--toolsand--force. With no terminal, setup cannot ask which tools to turn on or whether to restart open apps.--cert,--key,--ingressand--upstream-proxyare passed tovalar proxy enable.
0 when it worked. Otherwise its last line names the step it stopped at: fix the cause and run the script again. Set VALAR_VERBOSE=1 to log each step’s output.
On Windows, from a script run as SYSTEM, set VALAR_USER as in As SYSTEM, for a named user and run:
valar where only administrators can write, such as C:\Program Files\Valar: setup refuses a valar another account can change (V1A-2218). Run as SYSTEM, it needs no certificate of yours. From a script run as the signed-in user, run valar setup --force --tools … in place of the proxy enable and on lines of As the signed-in user, with the same --cert and --key.
Deploy
-
Install the CLI at a path the user can run, such as
/usr/local/bin/valar. See Install the CLI. -
Give each engineer a coding key. Create keys in the dashboard or with key automation. Store each key as that user with
valar configure --api-key <key>, or provide it through a protectedVALAR_API_KEYenvironment variable. Keep keys out of policy arguments and logs. -
Upgrade existing installs, as the user:
valar upgrade --force. Finish this before setting up the proxy. - Set up the proxy, from a root policy (proxy lane only, see below).
-
Turn on each harness, as the user:
-
Verify Claude Code and Claude Desktop on the proxy lane with
valar claude status --verifyorvalar claude-desktop status --verifyafter the user sends a request through that tool. For any other tool, or on the direct lane, usevalar <harness> status. -
Keep it current. Whenever your MDM installs a new
valarbinary, runvalar upgrade --forceas the user. Until it runs, most commands refuse (V1A-1903).
Set up the proxy from a root policy
Under MDM, bring your organization’s certificate. macOS trusts a new root only from an MDM profile or a person at the screen, so the certificatevalar proxy enable creates on its own fails from a policy (V1A-1113). Before the policy runs:
- Deliver your root CA as an MDM configuration profile with a Certificate payload. Until it arrives,
valar proxy enablestops withV1A-1106. - Put a leaf certificate for
api.anthropic.comand its key on the Mac, readable by root. See Create an organization-managed certificate.
--ingress external; if your network requires an outbound proxy, add --upstream-proxy. See Corporate networks.
Setting up the proxy does not turn on any harness. Running it again keeps each harness’s on/off choice but restarts the proxy, interrupting requests in flight, so run it on first setup and after renewing the certificate. If you use Cursor, also run it once after upgrading to a release with Cursor support, so the certificate covers Cursor (reissue an organization-managed certificate with Cursor’s names first).
Audit a device
valar status --json reports the device in one JSON document and ends with an exit code your audit script can branch on, so it never has to parse screen text. Run it as the user, like every command but proxy enable. It only reads: it never upgrades, never prompts, and never changes the device, so it is safe to run on a schedule.
When more than one applies, the code is the first in this order:
13, 1, 11, 12, 10. problems lists every one that applies.
These codes and result values are a contract: a code is never renumbered or reused, and a new state only adds a new code, so a script that branches on them keeps working across releases.
valar status --json reads the device and never asks the gateway whether the credential is accepted, so a coding key your organization has blocked under SSO sign-in still reads as "auth": "key" with the same exit code. A tool already switched on gets 403 sso_required on its next request. valar <tool> on and valar login open the browser sign-in and wait for it instead of writing the key; a run with no terminal and no browser (over SSH, or on Linux with no display) exits 1 with “this machine signs in to ValarCode through your identity provider: run valar login in a terminal to sign in again” and changes nothing.
authiskey,ssoornone.key_prefixis the non-secret start of the key, the same one the dashboard shows. The key itself is never printed.- With
auth: sso,emailis who is signed in andsessionislive,endedorunchecked, as Valar answered just now. While it islive,sign_in_expires_atis when the sign-in is scheduled to end (RFC 3339, UTC), so a script can warn before then; an admin can still end a sign-in earlier, which the nextsessionreports. harnesses[].stateison,off,partial,not installedorunknown.laneisproxyordirect.proxyappears only on macOS, Windows and Linux. On macOS,pac_armedsays whether a network service’s automatic proxy setting points at Valar. It is left out on Windows and Linux, and when it could not be read.org_offistruewhile your organization has Valar switched off.- With
layout_refused, the document holds onlyschema,version,result,exit_code,problemsandlayout. Until the upgrade runs, nothing else on the device can be described reliably.
schema number.
Restarts
Some changes apply only after a running app restarts. With a terminal,valar asks first. Under MDM it cannot ask, so pass --force to every valar upgrade and valar <harness> on|off. Without it, a command that needs a restart changes nothing and exits with an error (1 for on/off, 20 for upgrade). valar codex is the exception: without --force it changes the settings, leaves Codex running and exits 0, and new conversations go to Valar once the engineer restarts Codex.
--force restarts what the change needs:
- Claude Desktop quits and reopens in the background. If the app is asking the user to confirm quitting,
valarwaits up to 2 minutes for the answer, then fails withV1A-2017and leaves the configuration unchanged. - Cursor quits and reopens. On Windows,
valarcloses Cursor’s windows rather than ending it; see Cursor on Windows. - Claude Code closes interactive sessions and restarts background agents. Users reopen conversations with
claude --resume. - Codex closes the user’s Codex sessions and quits the Codex app, reopening it only if its window was open. Users reopen conversations with
codex resume; afteron, a reopened conversation stays with OpenAI until the user runs/forkin it.valar off --forcerestarts Codex the same way.
valar upgrade, --force also accepts any breaking changes the upgrade lists.
Restarts interrupt work in progress, so schedule forced runs at login or outside working hours. --force does not bypass certificate, ownership, or network checks.
When your MDM replaces the valar binary itself, the running proxy keeps the previous build until it restarts. From v1.1.35 the proxy notices the new binary within a minute and restarts itself as soon as no routed request is open; valar status names a daemon on an older build until then, and valar upgrade or valar proxy restart restarts it at once.
Without --force, a scripted valar claude on that finds Claude Code sessions open installs the direct lane rather than break them, and records it as a fallback. If your policy wants the proxy lane or nothing, pass --no-fallback instead: the command then changes nothing and exits 1 with V1A-1416, naming what withheld the proxy lane, so the policy can retry at a quieter hour.
Example: run as the signed-in user
If your MDM can run a script as the signed-in user, run thevalar commands directly. Otherwise, switch to that user from a root script, as this macOS example does. Adapt it to your fleet, for example by listing only the harnesses your engineers use.
Turn Valar off on a device
Runvalar off --proxy --force from a root policy with VALAR_USER set to the target account, as for valar proxy enable. It turns every harness off as the user, then removes the proxy, its services, its automatic proxy settings, and a root certificate it generated. It exits 0 only when nothing on the device still sends traffic to Valar; otherwise it exits non-zero and lists what remains. Without --proxy, valar off leaves the proxy installed.
Windows
On Windows, a deployment script can run in one of two ways. Choose by how your tool runs scripts.As SYSTEM, for a named user
Most device-management tools run scripts as SYSTEM. SetVALAR_USER to the signed-in user’s account, and valar does that user’s setup as that user. It adds the certificate it creates to the computer’s certificate store, so nobody is asked to confirm anything and no organization certificate is needed.
- Install the CLI where only administrators can write. A SYSTEM script must not run a program the user can replace. Set
VALAR_PREFIXbefore running the installer, for example toC:\Program Files\Valar. - Run the setup:
valar never chooses the user for you. With no VALAR_USER, a SYSTEM run stops (V1A-1004). It also stops if the account does not exist on the device (V1A-1005) or is not signed in (V1A-1004); have your tool retry later. Win32_ComputerSystem names the user at the device’s own screen and is empty for a Remote Desktop session.
Provide the coding key as VALAR_API_KEY through a protected channel, or store it first with valar configure --api-key <key> in the same script. Keep keys out of script arguments and logs.
Keep it current. When your tool installs a new valar.exe, run valar upgrade --force and then valar proxy restart the same way.
Remove it with valar off --proxy --force, run the same way. A user who runs valar proxy disable on their own is asked by Windows for administrator access, because the certificate is in the computer’s store. Without it, nothing is removed (V1A-1001). valar off needs no administrator access and stops all routing.
As the signed-in user
Run this way if your tool runs scripts as the user. No step needs administrator access. In Intune, set Run this script using the logged on credentials to Yes; with other tools, use their equivalent option. Creating Valar’s own certificate needs an administrator to approve Windows’ prompt, and an unattended script cannot. An unattendedvalar proxy enable that would create its own certificate therefore stops before changing anything (V1A-1128). Run it as SYSTEM instead (above), or deploy an organization certificate:
- Trust your organization’s root on each device: an Intune trusted certificate profile or Group Policy that installs it in the computer’s Trusted Root Certification Authorities store. See Trust and distribute.
- Deliver each device’s leaf bundle and key to a location only the signed-in user can read. Setup copies both into its own protected folder. If you deploy Cursor, the leaf must also cover Cursor’s servers; see Cursor on Windows.
- Install the CLI. The installer places it at
%USERPROFILE%\.local\bin\valar.exe. - Run the setup as the signed-in user:
valar configure --api-key <key> as the same user, or provide VALAR_API_KEY through a protected channel. Keep keys out of script arguments and logs.
If your organization applies one proxy setting to every user of the machine, proxy enable stops (V1A-1125): add --ingress external and deploy the Valar rule in your PAC. If your network requires an outbound proxy, add --upstream-proxy. See Corporate networks.
Keep it current. When your tool installs a new valar.exe, run valar upgrade --force and then valar proxy restart as the user. The restart moves the proxy services onto the new version.
Verify Claude Code and Claude Desktop with valar claude status --verify or valar claude-desktop status --verify after the user sends a request through that tool; Cursor and Codex have their own checks below. To check the device without Valar, see Deployment checks and diagnostics.
Cursor on Windows
On Windows, Cursor always goes through the on-device proxy. There is no direct lane, and--direct is refused. On devices where Cursor is installed, add it to the end of the script above:
- The proxy is set up and running. Until it is,
valar cursor onstops without changing Cursor and prints the fix, such asvalar proxy enableorvalar proxy restart. - Cursor 3.21.16 or newer is installed and signed in, on a paid plan (Pro, Business, or Enterprise). On the free plan, or before the engineer signs in to Cursor,
valar cursor onfails. On a new device, schedule it for after the engineer has signed in to Cursor. - The leaf certificate covers Cursor’s servers:
*.cursor.sh,*.api5.cursor.sh,*.us.api5.cursor.shand*.global.api5.cursor.sh, as well asapi.anthropic.com. If it does not,valar cursor onlists the names to add and stops without changing Cursor. Reissue the leaf with those names, then runvalar proxy enableagain. See Create an organization-managed certificate. - No other proxy setting is in the way. If Windows already uses another setup script (Use setup script), or a company proxy the Valar proxy does not go through,
valar cursor onstops without changing Cursor and prints the fix:--ingress externalor--upstream-proxyonvalar proxy enable. See Corporate networks.
--force, valar closes Cursor the way clicking X does, applies the change, and reopens it. It never ends Cursor by force. If Cursor asks the user whether to stop agents that are still working, valar waits 20 seconds, then stops without changing anything. If the account has Cursor open in another Windows sign-in, such as a disconnected remote desktop session, nothing changes, even with --force. Schedule the run at sign-in or outside working hours, and retry when it exits non-zero.
Verify with valar cursor status, as the user. It shows on, proxy lane and whether Valar only is on. partial means one of Valar’s settings was turned off inside Cursor, for example by signing out of Cursor; run the valar cursor on command that status prints.
Codex on Windows
On devices where Codex is installed, add it to the end of the script above:- Codex is installed for the user, the Codex CLI or the ChatGPT app. Codex need not have run yet:
valar codex oncreates%USERPROFILE%\.codex. Where Codex is not installed, it stops without changing anything. - Run it as the signed-in user, like every step above. Run as SYSTEM, it changes the system account’s Codex settings, not the engineer’s.
- Restarts. Without
--force,valardoes not close Codex. New conversations go to Valar once the engineer restarts Codex or the ChatGPT app; a conversation that was already open stays where it was. With--force, see Restarts.
valar codex status, as the user. It shows on.
Cowork on Windows
valar claude-desktop on in the script above also routes Claude Desktop’s local Cowork tab. There is no separate command for Cowork. For Cowork to reach Valar:
- Use the proxy lane. Set up the proxy before
valar claude-desktop on, as the script above does, and do not pass--direct. - Keep Cowork sessions on the device. Cowork sessions that run in the cloud go through claude.ai and are not routed. In Claude Desktop, Settings > Cowork > Only on this computer makes new sessions local; a session already in the cloud stays there.
- Let Claude Desktop finish its own Cowork setup. Claude Desktop runs local Cowork in a sandbox it calls a secure workspace, which needs Hyper-V. This is a Claude Desktop requirement, not a Valar one. If Claude Desktop shows Additional setup needed, turn on what it asks for.
valar claude-desktop on, send a request from the Cowork tab before any request from the Code tab, then run valar claude-desktop status --verify. It exits 0 once the proxy has forwarded a Claude Desktop request to Valar.
Linux
On Linux, every command runs as the user.valar proxy enable with a Valar-generated certificate asks for administrator access once, through sudo, to add the certificate to the system certificate store, so an unattended rollout either grants valar a passwordless sudo rule or brings your organization’s certificate (below), which needs none on a machine that never used a Valar-generated certificate. Switching a machine that did asks for administrator access once, to remove the old certificate. Claude Desktop is not supported on Linux yet, so turn on Claude Code and Cursor only.
- The user must be logged in. The proxy runs as a systemd user service, from login to logout. A container, WSL 1, or an account nobody is logged in to cannot run it, and
valar proxy enablestops without changes (V1A-1130). To keep the proxy running after logout, runsudo loginctl enable-linger <user>. - Cursor needs
certutil. Installlibnss3-tools(Debian, Ubuntu),nss-tools(Fedora, RHEL) ornss(Arch) before setup. Without it, Claude Code still uses the proxy, but Cursor cannot. - Bring your organization’s certificate for an unattended rollout. Deliver your root to the system certificate bundle, for Claude Code and Cursor’s chat, and to each user’s NSS database (
~/.pki/nssdb), for Cursor’s window; a new account needs the database created first (see Create an organization-managed certificate). Then run, as the user:
--ingress and --pac-port do not apply on Linux: no machine-wide proxy setting is written, and each harness’s on command sets its own. WSL 2 is not yet supported. See On Linux.
Update older policies
- Selecting the user: root policies that relied only on
HOMEmust setVALAR_USERor run as the user. - Windows scripts that run as SYSTEM: set
VALAR_USER, as in As SYSTEM, for a named user. Without it the run stops (V1A-1004). - Old command names:
valar claude-desktop proxystill works as an alias forvalar proxy. Onproxy enable,--force,--no-restart, and--offare accepted and ignored with a warning. Put--forceon the harness command instead, and use the harness’soffto stop routing.