On-device proxy

The on-device proxy is a shared local service for supported coding harnesses. Install it once, then control Valar routing separately for each harness.

The proxy runs on macOS and Windows 11. It currently supports Claude Code (claude) and Claude Desktop (claude-desktop), and on macOS Cursor (cursor). Other harnesses use separate routing integrations.

Set up the proxy

You need the Valar CLI and a coding key and a supported harness. On macOS you also need administrator access for certificate trust and proxy settings. On Windows, setup needs no administrator access. Run these commands from the account that will use Valar:

valar configure --api-key <your-coding-key>
valar proxy enable

Setup explains its machine changes before requesting administrator access on macOS, or before Windows asks you to confirm the local certificate. It installs the services without enabling harness routing or restarting applications. Existing ON/OFF choices stay unchanged. Then enable each harness you want to route. Replace <harness> with a supported harness name:

valar <harness> on

First-time activation may require restarting running sessions. Follow the harness command’s prompt and recovery instructions.

Routing controls

Command	Effect
`valar proxy enable`	Provision or refresh the shared proxy. Preserve each harness’s ON/OFF choice.
`valar <harness> on` / `off`	Change routing for that harness only.
`valar proxy restart`	Restart the installed proxy services. Active connections may be interrupted.
`valar proxy disable`	Remove the proxy after every harness has left the proxy lane.

On an established proxy setup, ordinary ON/OFF toggles do not restart sessions. OFF stops inspection and Valar routing; new connections pass through the local proxy to their original destination without decryption. Proxy settings stay installed so the next ON needs no restart. Changes to the certificate, connection settings, or routing lane may require one. The services remain available when all harnesses are OFF. To remove them, follow Remove the proxy.

Subscription-first routing

The proxy can apply subscription-first routing for integrations that support it. Today, quota-first for Claude is shared by Claude Code and Claude Desktop. It uses eligible included allowance before Valar; other harness subscriptions are not supported.

valar configure --quota-first=true

The running proxy reads this preference automatically. Use --quota-first=false to send all routed inference through Valar. Turning the preference off does not turn a harness off. See the harness documentation for supported accounts, model selection, counters, and reset commands.

Status and logs

valar proxy status
valar proxy logs
valar proxy logs -f

status reports the services, listeners, certificate, and enabled harnesses. logs prints recent proxy activity; -f keeps following it. To verify Valar forwarding, send a request that uses Valar, then check the harness:

valar <harness> status --verify

Verification requires a healthy proxy setup and a request successfully forwarded to Valar from that harness since routing was enabled. A subscription-served request does not satisfy the check. Restore subscription-first routing afterward if you disabled it for the test.

Corporate networks

Valar does not silently replace an existing corporate proxy or automatic-proxy policy. Configure the two directions separately:

Direction	Configuration
Harness → local Valar proxy	Your corporate PAC or the harness’s proxy settings
Local Valar proxy → network	`--upstream-proxy` with the corporate proxy’s concrete URL

Corporate PAC and an upstream proxy work together. Provision without replacing the corporate PAC, and explicitly configure the onward connection:

valar proxy enable \
  --ingress external \
  --upstream-proxy http://proxy.example.com:8080

Add --cert and --key when using organization-managed certificates. The upstream setting applies to every harness using this proxy, including subscription requests, other forwarded traffic, and undecrypted passthrough. Direct-lane sessions do not use this setting.

Outbound corporate proxy

If your shell already sets an outbound proxy, explicitly approve the same URL:

valar proxy enable --upstream-proxy http://proxy.example.com:8080

The proxy uses the recorded URL for outbound connections. For HTTPS it asks the corporate proxy to open a tunnel to the destination with HTTP CONNECT:

CONNECT api.valarhq.ai:443 HTTP/1.1
Host: api.valarhq.ai:443

After the corporate proxy accepts the tunnel, Valar’s local proxy establishes TLS to the destination through it and sends the request. Subscription/original-service traffic uses that service’s host instead, such as CONNECT api.anthropic.com:443. Valar selects the destination; the corporate proxy applies its access policy and carries the connection. It must allow both destinations. The hostname changes if you configured another Valar endpoint. Supply an HTTP or HTTPS proxy endpoint, not the URL of a .pac file. Valar does not evaluate PAC JavaScript or inherit its destination-specific proxy choices. If your PAC selects several corporate proxies, ask IT for one endpoint that can reach all required destinations. The corporate proxy can be unauthenticated or use Basic authentication: http://user:[email protected]:8080, with reserved characters percent-encoded. NTLM, Kerberos and browser-based sign-in are not supported, which rules out most Windows proxies that use integrated Windows authentication. Ask IT for an endpoint that accepts Basic or no authentication for the destinations below. The proxy credential is separate from your Valar coding key. If the corporate proxy inspects TLS, its certificate chain must be trusted on the machine. Do not disable TLS verification. Test both a Valar-served request and an original-service request after setup. The URL is saved in a user-only local file and its credentials are redacted in status output. The command-line argument itself can still appear in shell history or process listings; use your organization’s approved secret-handling process. A later proxy enable preserves the saved upstream if you omit the flag. Use --upstream-proxy <new-url> to replace it. --upstream-proxy="" clears it only when no conflicting outbound proxy remains in the shell. Never point the upstream at a Valar loopback listener.

How this relates to HTTPS_PROXY

Programs launched from your shell can use its HTTPS_PROXY value if they support that variable. It does not configure the Valar daemon. The daemon reads only its saved upstream setting, which prevents it from accidentally proxying back to itself.

If HTTPS_PROXY already points to a corporate proxy, proxy enable requires the same URL to be explicitly approved by --upstream-proxy, or already recorded from an earlier setup.
Claude Code’s own proxy settings point to its local Valar listener after on. Its requests then travel through Valar and onward through the configured corporate proxy.
A managed proxy setting takes precedence over user settings. IT must point it to the correct local listener; configuring an upstream does not override managed policy.
The valar commands themselves use standard proxy environment settings for their HTTP calls. On a PAC-only network that blocks direct access, provide the corporate HTTPS_PROXY value to CLI setup/upgrade commands as well. The saved daemon upstream is not a proxy setting for every program on the machine.

A proxy set in network settings

A fixed proxy in the machine’s network settings (on Windows, Use a proxy server in Settings > Network & internet > Proxy) is treated the same way as HTTPS_PROXY. Apps that read the automatic-proxy document try it before the fixed proxy, so Valar’s document would otherwise move those apps off your corporate proxy. proxy enable therefore stops and names the proxy until you approve that exact proxy:

valar proxy enable --upstream-proxy http://proxy.example.com:8080

The approval must name the same scheme, host and port as the network setting. It may add a username and password that the network setting does not carry. Once it is approved, Valar’s automatic-proxy document keeps your proxy for every other app:

Hosts Valar routes try the local Valar proxy first, then your corporate proxy.
Hosts on the proxy’s bypass list and local addresses connect directly, as before. On macOS, plain host names do too.
Every other host goes to your corporate proxy.

The document names only the proxy’s host and port, never its credentials. proxy enable also stops when network services name different proxies or different bypass lists, or when a bypass entry cannot be reproduced exactly. It names the entry so you can rewrite it. valar proxy status warns if the network setting later changes to a proxy that is not approved. A machine set up with an earlier release over a fixed proxy keeps working as it did. valar proxy status warns that other apps are bypassing that proxy and shows the --upstream-proxy command that fixes it.

Automatic proxy discovery (WPAD)

Automatic proxy discovery does not stop proxy enable. When discovery is on (on Windows, Automatically detect settings, which is on by default), proxy enable checks whether the current network publishes a proxy script. Apps such as Claude Desktop use a discovered script ahead of Valar’s document, so on a network that publishes one, Claude Desktop may not be routed through Valar. proxy enable and valar proxy status warn only in that case. To route Claude Desktop there, IT can add the Valar rule to the published script and provision with --ingress external, as described below.

Administrator-managed traffic steering

If IT owns the automatic-proxy policy or managed app settings, provision without replacing them:

valar proxy enable --ingress external

IT must then direct each harness to its own local listener. This option does not redirect traffic by itself. Current default addresses are listed below. Each harness must use its own listener:

Purpose	Address
Claude Desktop proxy	`127.0.0.1:18080`
Claude Code proxy	`127.0.0.1:18082`
Cursor proxy (macOS)	`127.0.0.1:18083`
Automatic-proxy document	`http://127.0.0.1:18081/proxy.pac`

Use valar proxy status for the installed addresses. Set custom ports with --port <harness>=<port> and --pac-port <port>. Existing corporate outbound proxy requirements still apply with external steering; combine --ingress external with --upstream-proxy when both are needed.

Add Valar to an existing corporate PAC

Keep the corporate PAC URL. Add an exact-host rule for supported traffic before the existing catch-all rules. For the current PAC-based integration, Claude Desktop, use its listener (18080 by default):

function FindProxyForURL(url, host) {
  var normalizedHost = host.toLowerCase();
  if (normalizedHost === "api.anthropic.com" ||
      normalizedHost === "api.anthropic.com.") {
    return "PROXY 127.0.0.1:18080; PROXY proxy.example.com:8080";
  }
  return CorporateProxyForURL(url, host);
}

function CorporateProxyForURL(url, host) {
  // Keep your existing FindProxyForURL body here, including its exclusions.
  // This minimal example sends other traffic through the corporate proxy.
  return "PROXY proxy.example.com:8080";
}

The same PAC works on macOS and Windows. On Windows, deliver its URL through the Use setup script proxy setting, with Intune or Group Policy. Rename your existing FindProxyForURL to CorporateProxyForURL without changing its body, then add the wrapper. The selected host uses the new local-proxy rule; all other hosts retain their existing corporate rules. Review that override with IT. The final function above is only a minimal example. Deploy this PAC change only to devices where Valar is provisioned. Keep local proxy/PAC addresses reachable without sending them back through another proxy. The semicolon-separated return value is a fallback list, not a chain. The app tries the local proxy first and may try the corporate proxy directly if the local proxy is unavailable. To make a healthy local Valar proxy send onward through the corporate proxy, you still need --upstream-proxy. Choose the failure policy with IT:

PAC result for the selected host	If the local proxy is unavailable
`PROXY 127.0.0.1:18080; PROXY proxy.example.com:8080`	The app may connect through the corporate proxy without Valar.
`PROXY 127.0.0.1:18080`	No alternate route is supplied; affected requests can fail.

Do not append DIRECT if your organization prohibits direct internet access. PAC fallback is client-dependent and does not guarantee retrying an active request or bypassing HTTP errors. An upstream refusal returned by Valar is not the same as an unreachable local proxy. A PAC function receives a URL and host, not the calling application’s identity. This host rule also affects other PAC-aware apps requesting that host. They reach the Desktop listener and follow its routing switch. Review that scope with IT; do not send multiple harnesses to one listener when you need independent controls.

Configure harnesses that do not use system PAC

Cursor does not use the system PAC either; valar cursor on points Cursor’s own http.proxy setting at its listener. Claude Code does not use the system PAC for its proxy connection. Run valar claude on to configure its listener, or merge equivalent proxy values into IT-managed Claude settings:

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:18082",
    "https_proxy": "http://127.0.0.1:18082",
    "HTTP_PROXY": "http://127.0.0.1:18082",
    "http_proxy": "http://127.0.0.1:18082",
    "NO_PROXY": "localhost,127.0.0.1,::1",
    "no_proxy": "localhost,127.0.0.1,::1"
  }
}

Claude Code reads IT-managed settings from /Library/Application Support/ClaudeCode/managed-settings.json on macOS and C:\Program Files\ClaudeCode\managed-settings.json on Windows. Merge the proxy settings into the existing policy without replacing the whole file. For NO_PROXY and no_proxy, add the listed loopback addresses to your required internal bypasses rather than replacing the existing lists. Neither list should exclude api.anthropic.com or use *, which would bypass Valar. A conflicting lowercase proxy value can take precedence over uppercase, so keep both forms consistent. Use the installed listener address if you changed the default port. Even when IT delivers the connection settings, run the harness’s on command to enable Valar routing. Settings alone do not turn its routing switch on.

Roll out and verify corporate networking

Provision with --ingress external, the corporate upstream, and trusted certificates.
Deploy the PAC rule and any app-specific proxy settings to the selected devices.
Activate each supported harness and follow any restart prompt. A PAC update can remain cached in a running app.
Check valar proxy status for external ingress and the redacted upstream. Check each harness’s status and send a Valar-served request.
Run each harness’s status --verify. Test subscription/native traffic separately; successful Valar verification confirms only the Valar path.
In a pilot device, test your chosen local-proxy failure policy and confirm the corporate proxy sees the intended destinations.

When retiring the deployment, turn the harnesses OFF, remove IT-managed local proxy pointers/PAC rules, and reload affected apps before removing the shared proxy. Valar cannot remove rules inside your corporate PAC or managed settings.

Certificates and machine changes

By default, setup:

Creates a local root certificate named Valar Local Root CA and trusts its public certificate: in the System keychain on macOS, and in your own user certificate store (CurrentUser\Root) on Windows.
Uses its private key once to sign a leaf certificate covering the supported harness destinations, then discards the root private key without saving it to disk.
Stores the leaf certificate and private key under ~/.valar/proxy/ with user-only permissions.
Installs two per-user background services: the proxy and the automatic-proxy document server.
Configures the automatic-proxy URL, unless you selected external steering: on each enabled network service on macOS, and in your Windows proxy setting (Use setup script) on Windows.

The generated root is valid for 1,095 days and the leaf for 730 days. On macOS, administrator privileges handle certificate trust and system proxy changes, and can read protected certificate inputs supplied during root-run provisioning. The services and user configuration belong to the selected user. One user owns the proxy installation on a machine; on Windows, setup refuses while another account’s proxy is running (V1A-1015), because the listening ports are shared by every account.

On Windows

Setup changes only your own Windows account and never asks for administrator access. Windows asks you once to confirm the Valar root certificate; choose Yes. If you choose No, setup stops without changes (V1A-1123); run valar proxy enable again and accept. If your organization’s policy does not trust certificates that users install, setup stops without changes (V1A-1124); deploy an organization-managed certificate instead. Setup stops before making changes when:

A policy makes Windows use one proxy setting for every user of the machine (V1A-1125). Your own setting would be ignored, so have IT add the Valar rule to the machine’s script and provision with --ingress external. See Administrator-managed traffic steering.
A port it needs is in use or inside a range Windows reserves for Hyper-V or WSL (V1A-1121). Run netsh interface ipv4 show excludedportrange protocol=tcp to list the reserved ranges, then pick another port with --port or --pac-port.
It would create a certificate but no one is at a terminal to accept the Windows warning (V1A-1128). For unattended installs, use an organization certificate. See Roll out with MDM.

Each integration defines which local traffic reaches the proxy. It is not a system-wide VPN and does not cover remote sessions automatically. Check the harness documentation for coverage and connection settings. The proxy and PAC services listen only on this machine’s loopback addresses, not on LAN interfaces. Setup configures IPv4 and IPv6 loopback listeners where available. On macOS, if a VPN, dock, or network change adds an enabled network service, rerun valar proxy enable to apply Valar-managed automatic-proxy settings to it. On Windows, the setting covers Wi-Fi and Ethernet, so a new network of either kind needs no action. A VPN built into Windows keeps its own proxy setting, which Valar does not change. With --ingress external, have IT update its managed proxy settings or PAC coverage instead. Verify routing on the new connection.

Installed files and cleanup

These paths are relative to ~/.valar/ (%USERPROFILE%\.valar\ on Windows) unless noted. The removal column describes a successful valar proxy disable; partial cleanup keeps the installation record for retry.

Files	Purpose	On removal
`config.json`	Coding key and shared CLI preferences	Kept; proxy setup records cleared
`cli.log`, `cli-<timestamp>.log`	CLI support log and rotated history	Kept
`proxy-pac-ownership.json`	Recognizes disabled Valar PAC settings during later setup	Kept
`proxy/cert.pem`, `proxy/cert.key` `proxy/leaf.pem`, `proxy/leaf.key`	Generated or copied device certificate and private key	Removed; original IT-supplied files untouched
`proxy-state.json`	Installed listeners, certificate paths, ownership and generated-root fingerprint	Removed after cleanup succeeds
`proxy-forwarding.json`, `proxy.version`	Forwarding status and running build	Removed
`proxy.log`, `proxy.log.1`, `proxy.log.lock` `pac.log`, `pac.log.1` `proxy.boot.log`, `pac.boot.log`	Request, PAC and service-startup diagnostics	Removed
`claude/desktop-quota-first-holds.json`	Saved temporary subscription holds	Removed
`~/Library/LaunchAgents/ai.valarhq.valar.proxy.plist` `~/Library/LaunchAgents/ai.valarhq.valar.pac.plist`	Per-user proxy and PAC services (macOS)	Removed
Task Scheduler `\Valar\ai.valarhq.valar.proxy` `\Valar\ai.valarhq.valar.pac`	Per-user proxy and PAC services (Windows)	Removed
`%LOCALAPPDATA%\Valar\proxy\valar.exe`	The copy the Windows services run	Removed

Organization-managed certificate trust is preserved. Valar removes only the root certificate whose fingerprint this installation recorded as Valar-generated. Files you placed alongside the proxy’s own files are not removed.

Organization-managed certificates

If your organization supplies the certificate, trust its root through your normal device-management process, then run:

valar proxy enable --cert /absolute/path/leaf-bundle.pem --key /absolute/path/leaf.key

Supply both flags. The bundle must contain a valid end-entity leaf first, followed by its intermediate certificates. The leaf must match the private key and chain to a root the operating system already trusts. It must cover every supported destination: api.anthropic.com and, for Cursor, *.cursor.sh, *.api5.cursor.sh, *.us.api5.cursor.sh and *.global.api5.cursor.sh. On macOS, root-run provisioning can read protected certificate/key sources without changing their ownership or permissions. Symlinked paths are supported; their targets must be regular PEM files. Without root, both sources must be readable by the user; otherwise rerun the same provisioning command with sudo. The installed copies remain private to the selected user. Valar copies the leaf and key into its protected local directory. It does not create, rotate, or remove your organization’s root CA. Renew organization-managed certificates through your PKI and rerun setup with the replacement files. valar proxy restart keeps a healthy certificate. If a Valar-generated certificate needs replacement, it can request administrator access on macOS, or show the Windows certificate warning, to install a fresh one. A replacement certificate may require restarting affected apps.

Create an organization-managed certificate

Use your existing PKI when available. The example below creates a private root and one device leaf on a protected signing machine. Keep the root key there; distribute only the root’s public certificate through MDM and the device’s leaf bundle/key through a protected channel. Issue a separate leaf key for each device.

1. Create the root once, on the signing machine

Use a new directory for a new CA. Do not overwrite an existing CA when enrolling another device.

umask 077
mkdir organization-proxy-ca
cd organization-proxy-ca

cat > root.cnf <<'CONFIG'
[req]
prompt = no
distinguished_name = root_name
x509_extensions = root_ca
[root_name]
O = Example Organization
CN = Example Organization Local Proxy Root
[root_ca]
basicConstraints = critical,CA:TRUE,pathlen:0
keyUsage = critical,keyCertSign,cRLSign
subjectKeyIdentifier = hash
CONFIG

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
  -pkeyopt ec_param_enc:named_curve -out root.key
openssl req -new -x509 -key root.key -sha256 -days 3650 \
  -config root.cnf -extensions root_ca -out root.pem

root.key can issue certificates trusted by enrolled devices. Store it offline or in your PKI’s protected signing system. Never deploy it to user devices. The validity periods in this example are choices for your PKI to review, not Valar requirements.

2. Issue a leaf for each device

Run from the CA directory. Choose a new directory name for each device or renewal; this example uses device-001.

umask 077
mkdir device-001

cat > device-001/leaf.cnf <<'CONFIG'
[server_leaf]
basicConstraints = critical,CA:FALSE
keyUsage = critical,digitalSignature
extendedKeyUsage = serverAuth
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
subjectAltName = DNS:api.anthropic.com,DNS:*.cursor.sh,DNS:*.api5.cursor.sh,DNS:*.us.api5.cursor.sh,DNS:*.global.api5.cursor.sh
CONFIG

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
  -pkeyopt ec_param_enc:named_curve -out device-001/leaf.key
openssl req -new -key device-001/leaf.key \
  -subj "/O=Example Organization/CN=Valar local proxy device-001" \
  -out device-001/leaf.csr
openssl x509 -req -in device-001/leaf.csr \
  -CA root.pem -CAkey root.key -CAcreateserial -CAserial root.srl \
  -sha256 -days 365 -extfile device-001/leaf.cnf \
  -extensions server_leaf -out device-001/leaf.pem
cat device-001/leaf.pem root.pem > device-001/leaf-bundle.pem

The supported destinations are api.anthropic.com and, for Cursor, *.cursor.sh, *.api5.cursor.sh, *.us.api5.cursor.sh and *.global.api5.cursor.sh. Update SANs when the supported harness destinations change. This example root signs device leaves directly; its pathlen:0 constraint does not permit intermediate CAs. If you use an existing PKI with intermediates instead, include them after the leaf in the bundle. Root inclusion is optional; trust must still be installed separately.The recipe uses real extension files and an explicit serial-file path, so it works with macOS LibreSSL and OpenSSL. Serialize issuance when using this simple shared serial file; production PKI should manage issuance and serial numbers.

3. Verify before distributing

openssl verify -CAfile root.pem -purpose sslserver device-001/leaf.pem
openssl x509 -in device-001/leaf.pem -noout -dates -subject -issuer
openssl x509 -in device-001/leaf.pem -noout -text

openssl x509 -in device-001/leaf.pem -pubkey -noout > device-001/cert-public.pem
openssl pkey -in device-001/leaf.key -pubout > device-001/key-public.pem
cmp device-001/cert-public.pem device-001/key-public.pem

Verification should report OK, and cmp should exit successfully. Confirm the leaf has CA:FALSE, server authentication usage, and the required SAN. These checks validate the issued files; they do not install macOS trust. valar proxy enable also checks hostname coverage, validity, matching keys, and the machine’s trust store before accepting the certificate.

Trust and distribute

File	Destination
`root.pem`	MDM trusted-root certificate profile on enrolled devices
`leaf-bundle.pem`	The intended device; root-only staging is supported for root-run provisioning
`leaf.key`	Protected staging on the same device; installed copy is private to the selected user
`root.key`	Signing system only; never deploy

The leaf private key must be an unencrypted PEM file so the background service can start unattended. Protect it through filesystem permissions and secure delivery. PKCS#8, SEC1 EC, and PKCS#1 RSA encodings are supported. This file-based setup does not accept a keychain-only or hardware-key reference. Wait for the MDM trust profile to apply before provisioning. For a controlled manual pilot, your administrator can install the public root into the macOS System keychain:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain /absolute/path/root.pem

On Windows, deploy the root with an Intune trusted certificate profile or Group Policy into the computer’s Trusted Root Certification Authorities store. For a manual pilot, from an administrator PowerShell:

certutil -addstore Root C:\path\root.pem

This installs system trust; it is separate from copying the leaf files. Valar does not remove organization-managed trust during teardown.

Renew certificates

Issue a new device leaf before expiry, verify it, then rerun proxy enable --cert ... --key ... with the new files. Replacing source files or updating their symlinks alone does not replace Valar’s installed copies. Reapply each routed harness’s on command and follow any restart instructions; verify forwarding afterward. When rotating the root, distribute and verify the new trust profile before provisioning leaves signed by it. Keep the old root until devices have moved, then retire it through your MDM/PKI process. Valar does not manage organization certificate revocation or trust-profile removal.

Deploy with MDM

See Roll out with MDM for deploying the CLI, the proxy, and each harness from Jamf, Kandji, Intune, or other MDM tools.

Remove the proxy

Run valar proxy status to see which harnesses use the proxy.
Run valar <harness> off for each harness still on the proxy lane.
Save active work. If IT manages proxy settings or PAC rules, have IT remove the local Valar pointers and reload affected apps.
Remove the shared component:

valar proxy disable

OFF keeps the proxy installed. An OFF harness can still send encrypted traffic through it. Removing the proxy may interrupt running sessions until they reload their connection settings. proxy disable refuses while any harness remains on the proxy lane, even with --force. Once all are OFF, it checks for running sessions that may still depend on the proxy and asks before proceeding. Read the restart instructions: automatic restart is available only where supported; other sessions need a manual restart. For unattended removal, --force approves this interruption. --no-restart suppresses automatic app restarts and leaves that work to your deployment process. Neither flag makes a running session independent of the proxy. Removal clears Valar-owned automatic-proxy settings, removes its services and proxy files, and removes only a root certificate recorded as generated by this installation. It preserves organization-managed trust and the CLI support log. With external steering, IT must remove its own proxy pointers. Check the exit code and run valar proxy status. If removal is incomplete, fix the reported cause and retry. Do not delete the installation records by hand while recovery is pending.

Verify certificate removal

For a Valar-generated root, record root_fingerprint from ~/.valar/proxy-state.json before disabling the proxy. Successful cleanup removes that file. This check does not apply to organization-managed roots, which Valar leaves in place.After valar proxy disable, list matching certificates in the System keychain:

security find-certificate -a -Z -c "Valar Local Root CA" \
  /Library/Keychains/System.keychain

Compare the reported SHA-256 hashes with the recorded fingerprint, ignoring colons and letter case. The recorded fingerprint should no longer appear. Another certificate with the same name may remain if it belongs to your organization or another installation; do not delete certificates by name alone.On Windows, list the matching certificates in your user store instead:

Get-ChildItem Cert:\CurrentUser\Root |
  Where-Object Subject -like "*Valar Local Root CA*" |
  ForEach-Object { $_.GetCertHashString([System.Security.Cryptography.HashAlgorithmName]::SHA256) }

Compare each SHA-256 hash with the recorded fingerprint the same way.These commands only read the certificate store. If the recorded certificate remains, follow the removal error and retry valar proxy disable. A warning about a remaining trust setting after its certificate was removed is a separate cleanup issue; it does not mean the certificate is still installed.

Deployment checks and diagnostics

Use exit codes to detect failure, then read the full error and its next steps. A nonzero exit can describe partial completion; do not assume every file or service was rolled back.

Message/code	What to check
`V1A-1001`	Required administrator access was unavailable. Read which operation failed and whether any earlier work completed.
`V1A-1004`	Root execution has no selected user. Run from that user’s session or select the account in your root policy.
`V1A-1008`	The selected user’s home directory is absent. Enroll/log in the user before provisioning.
`V1A-1120`	Provisioning could not confirm the listeners were ready. Check service startup logs and `valar proxy status`.
`V1A-1121`	A listening port is in use, or reserved by Windows for Hyper-V or WSL. Choose another with `--port` or `--pac-port`.
`V1A-1123`	Windows: the certificate warning was declined. Run `valar proxy enable` again and accept.
`V1A-1124`	Windows: policy does not trust user-installed certificates. Deploy an organization certificate.
`V1A-1125`	Windows: policy applies one proxy setting to every user. Provision with `--ingress external` and have IT add the Valar rule.
`V1A-1128`	Windows: an unattended run would need someone to accept the certificate warning. Pass `--cert` and `--key`.
`V1A-1800` / `V1A-1801`	Harness verification found unhealthy/unconfigured routing or no successful forwarded request.
`V1A-1902`	Upgrade or migration did not finish. Resolve the reported cause and use the upgrade recovery guidance.

The local services run as the selected user under ~/Library/LaunchAgents/. Their labels are ai.valarhq.valar.proxy and ai.valarhq.valar.pac. From that user’s session, inspect them without changing state:

launchctl print "gui/$(id -u)/ai.valarhq.valar.proxy"
launchctl print "gui/$(id -u)/ai.valarhq.valar.pac"
scutil --proxy

On Windows, from that user’s session:

schtasks /Query /TN \Valar\ai.valarhq.valar.proxy
schtasks /Query /TN \Valar\ai.valarhq.valar.pac
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v AutoConfigURL

After successful removal, both service lookups should report that the jobs are absent. With external ingress, the corporate PAC can remain configured; IT must remove the local Valar rules. With Valar-managed PAC, macOS may keep a disabled URL string. An enabled stale pointer still needs cleanup.

Troubleshooting

Symptom	Next step
A proxy-supported harness uses the direct lane	Read its status explanation. Provision the proxy and run the harness’s `on` command when ready.
Certificate or connection settings changed	Re-run the harness’s `on` command and follow any restart prompt.
Proxy services are unavailable	Run `valar proxy status`, then `valar proxy restart`; inspect `valar proxy logs`.
A corporate proxy is already configured	Keep the policy in place. Use an explicitly approved outbound proxy and/or IT-managed steering.
`proxy enable` stops on a proxy set in network settings	Approve that exact proxy with `--upstream-proxy`. See A proxy set in network settings.
Status says other apps are bypassing the system proxy	Run the `--upstream-proxy` command status shows.
Status warns about a published discovery script	Claude Desktop may not be routed on this network. See Automatic proxy discovery (WPAD).
Requests work but Valar verification fails	Check the selected lane and quota-first state; send a request that uses Valar, then retry.
A session still uses its previous routing	Follow the harness’s recovery warning and restart the affected session.

A session that still depends on an unavailable proxy can fail until the service is restored or its connection settings are reloaded. Some integrations can fall back to a direct connection; that does not prove Valar routing. Verify each harness after setup or repair. For command/setup failures, collect the CLI support log. For service startup failures, inspect ~/.valar/proxy.boot.log and ~/.valar/pac.boot.log (under %USERPROFILE%\.valar\ on Windows).

Support logs

The CLI writes command and setup diagnostics automatically to ~/.valar/cli.log; no logging option is needed. Logging is best effort: a permissions problem or an early refusal can prevent a record, so keep the terminal error too.

Collect logs and check their contents

The CLI support log records command names, CLI/OS versions, exit codes and sanitized errors. Proxy setup failures can also include network-service names and proxy-setting classifications.It does not record full command arguments, configuration or environment contents, request bodies, or proxy traffic. Error text is sanitized to redact recognized credentials, argument values, URLs, account names and absolute paths. Review the file before sharing it.Rotation keeps the live log and one ~/.valar/cli-<timestamp>.log backup, about 2 MiB combined. The live file has the latest records; include the backup if support needs older history. Both survive valar proxy disable.valar proxy logs and the service-startup logs are separate diagnostics; the CLI support log’s redaction rules do not apply to them. Review those logs separately before sharing.

Getting started

Build agents

Run in production

ValarCode

Platform

On-device proxy

Set up the proxy

Routing controls

Subscription-first routing

Status and logs

Corporate networks

Outbound corporate proxy

How this relates to HTTPS_PROXY

A proxy set in network settings

Automatic proxy discovery (WPAD)

Administrator-managed traffic steering

Add Valar to an existing corporate PAC

Configure harnesses that do not use system PAC

Roll out and verify corporate networking

Certificates and machine changes

On Windows

Organization-managed certificates

Create an organization-managed certificate

Trust and distribute

Renew certificates

Deploy with MDM

Remove the proxy

Deployment checks and diagnostics

Troubleshooting

Support logs

​Set up the proxy

​Routing controls

​Subscription-first routing

​Status and logs

​Corporate networks

​Outbound corporate proxy

​How this relates to HTTPS_PROXY

​A proxy set in network settings

​Automatic proxy discovery (WPAD)

​Administrator-managed traffic steering

​Add Valar to an existing corporate PAC

​Configure harnesses that do not use system PAC

​Roll out and verify corporate networking

​Certificates and machine changes

​On Windows

​Organization-managed certificates

​Create an organization-managed certificate

​Trust and distribute

​Renew certificates

​Deploy with MDM

​Remove the proxy

​Deployment checks and diagnostics

​Troubleshooting

​Support logs

Set up the proxy

Routing controls

Subscription-first routing

Status and logs

Corporate networks

Outbound corporate proxy

How this relates to HTTPS_PROXY

A proxy set in network settings

Automatic proxy discovery (WPAD)

Administrator-managed traffic steering

Add Valar to an existing corporate PAC

Configure harnesses that do not use system PAC

Roll out and verify corporate networking

Certificates and machine changes

On Windows

Organization-managed certificates

Create an organization-managed certificate

Trust and distribute

Renew certificates

Deploy with MDM

Remove the proxy

Deployment checks and diagnostics

Troubleshooting

Support logs