Network Proxy

Route traffic through an HTTP/HTTPS proxy for corporate networks and firewalls

xiantong can route all network traffic through an HTTP or HTTPS proxy. This is useful for corporate networks that require proxy access, firewalls that block direct connections, or environments where network inspection is required.

Configuration#

Open Settings → Network and configure:

Settings are stored in ~/.xiantong/config.json under the networkProxy key:

{
"networkProxy": {
"enabled": true,
"httpProxy": "http://proxy.corp.com:8080",
"httpsProxy": "http://proxy.corp.com:8080",
"noProxy": "localhost,127.0.0.1,.internal.com"
}
}

Changes take effect immediately — no restart required.

How It Works#

When proxy is enabled, xiantong routes traffic at two levels:

1. Node.js (main process) — All fetch() calls (OAuth flows, MCP server connections, API requests) are routed through an undici ProxyAgent that uses HTTPS CONNECT tunneling for secure connections.
2. Electron (browser windows) — Browser pane requests and OAuth browser windows use Chromium’s built-in proxy support via session.setProxy().
3. SDK subprocesses — The Claude Code subprocess receives HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables automatically.

Proxy Authentication#

For proxies that require authentication, include credentials in the URL:

http://username:password@proxy.corp.com:8080

Proxy credentials are stored in plain text in config.json. Use environment-level proxy configuration if your security policy requires encrypted credential storage.

No Proxy Rules#

The No Proxy field accepts a comma-separated list of bypass rules:

localhost and 127.0.0.1 are not automatically bypassed. If your setup requires direct access to local services (e.g., local MCP servers), add them to the No Proxy list explicitly.

TLS-Intercepting Proxies (Corporate Firewalls)#

Many corporate proxies perform TLS inspection by re-signing HTTPS traffic with an internal Certificate Authority (CA). This causes fetch failed errors because Node.js does not trust the proxy’s CA by default.

Symptoms#

• OAuth sign-in fails with “fetch failed” or returns silently with no browser window
• MCP server connections fail behind the corporate network but work on personal networks
• Browser pane requests work fine (Chromium uses the system certificate store) but agent-initiated requests fail

Solution#

Set the NODE_EXTRA_CA_CERTS environment variable to point to your corporate proxy’s CA certificate before launching xiantong:

• macOS

• Windows

• Linux

One-time launch from terminal:

NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem open -a "xiantong"

**Permanent (all apps, including Dock/Spotlight launches):**Shell profile variables (~/.zshrc) only apply to terminal sessions. To set environment variables for packaged apps launched from Dock or Spotlight, use launchctl:

# Set for the current user session (survives reboots on modern macOS)
launchctl setenv NODE_EXTRA_CA_CERTS /path/to/corporate-ca.pem

Then relaunch xiantong. To verify it took effect:

launchctl getenv NODE_EXTRA_CA_CERTS

To remove it later:

launchctl unsetenv NODE_EXTRA_CA_CERTS

On macOS 10.10+ launchctl setenv persists across reboots for GUI sessions. If your organisation uses an MDM, your IT department can also deploy this via a LaunchAgent plist:

<!-- ~/Library/LaunchAgents/com.xiantong.proxy-ca.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.xiantong.proxy-ca</string>
<key>ProgramArguments</key>
<array>
<string>/bin/launchctl</string>
<string>setenv</string>
<string>NODE_EXTRA_CA_CERTS</string>
<string>/path/to/corporate-ca.pem</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>

One-time launch from PowerShell:

$env:NODE_EXTRA_CA_CERTS = "C:\path\to\corporate-ca.pem"
& "$env:LOCALAPPDATA\xiantong\xiantong.exe"

**Permanent (all apps, including Start Menu/desktop launches):**Option A — via System Properties UI:

1. Press Win + R, type sysdm.cpl, press Enter
2. Go to the Advanced tab → click Environment Variables
3. Under User variables, click New
4. Variable name: NODE_EXTRA_CA_CERTS
5. Variable value: C:\path\to\corporate-ca.pem
6. Click OK on all dialogs
7. Sign out and back in (or reboot) for the change to take effect

Option B — via PowerShell:

[System.Environment]::SetEnvironmentVariable(
"NODE_EXTRA_CA_CERTS",
"C:\path\to\corporate-ca.pem",
"User"
)

You must sign out and back in (or reboot) for the change to take effect in Explorer-launched apps. Terminal sessions pick it up immediately after opening a new window.

To remove it later, delete the variable from System Properties, or run:

[System.Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", $null, "User")

For organisation-wide deployment, IT can set this as a Machine-level variable (via the System Properties UI or Group Policy).

One-time launch from terminal:

NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem xiantong

**Permanent (all apps, including desktop launches):**Add to ~/.profile (read by login shells) and ~/.config/environment.d/proxy-ca.conf (read by systemd user sessions, which most modern desktop environments use):

# ~/.config/environment.d/proxy-ca.conf
NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

Then log out and back in. To verify:

systemctl --user show-environment | grep NODE_EXTRA_CA_CERTS

On older desktop environments that don’t use systemd user sessions, ~/.pam_environment or ~/.xprofile may be needed instead.

Obtaining the CA Certificate#

Your IT department should provide the corporate proxy CA certificate. If you need to extract it yourself:

# Connect through the proxy and capture the certificate chain
openssl s_client -connect api.anthropic.com:443 -proxy proxy.corp.com:8080 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > corporate-ca.pem

The certificate must be in PEM format (begins with -----BEGIN CERTIFICATE-----). If you receive a .cer or .der file, convert it:

openssl x509 -inform DER -in corporate-ca.cer -out corporate-ca.pem

Troubleshooting#

”Fetch failed” on OAuth sign-in#

This typically indicates a TLS-intercepting proxy. See the TLS-Intercepting Proxies section above.

Proxy works for browsing but not for OAuth#

The browser pane uses Chromium’s certificate store (which includes system-installed CAs), while OAuth discovery and token exchange use Node.js fetch() (which only trusts Node’s built-in CA bundle). Set NODE_EXTRA_CA_CERTS to bridge this gap.

MCP servers fail to connect#

Ensure the MCP server’s hostname is not in the No Proxy list (unless you want direct access). For local MCP servers (stdio transport), proxy settings do not apply — they run as local subprocesses.

Proxy authentication fails#

• Verify credentials work with curl: curl -v --proxy http://user:pass@proxy:8080 https://api.anthropic.com
• URL-encode special characters in the password (e.g., p%40ss for p@ss)
• Some corporate proxies use NTLM authentication, which is not supported directly. Consider using cntlm as a local NTLM-to-Basic proxy bridge.

Verifying proxy is active#

Check the application log for proxy configuration at startup:

[proxy] Applying proxy settings: { enabled: true, hasHttpProxy: true, hasHttpsProxy: true, hasNoProxy: true }

Log location: ~/Library/Logs/@xiantong/electron/main.log (macOS)