Network Proxy - Craft Agents

Craft Agents 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:

Field	Description	Example
Enable Proxy	Toggle proxy routing on/off	—
HTTP Proxy	Proxy URL for HTTP requests	`http://proxy.corp.com:8080`
HTTPS Proxy	Proxy URL for HTTPS requests (uses HTTP Proxy as fallback if not set)	`http://proxy.corp.com:8080`
No Proxy	Comma-separated list of hosts/domains to bypass	`localhost,127.0.0.1,.internal.com`

Settings are stored in ~/.craft-agent/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, Craft Agents routes traffic at two levels:

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.
Electron (browser windows) — Browser pane requests and OAuth browser windows use Chromium’s built-in proxy support via session.setProxy().
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:

Pattern	Matches
`*`	All hosts (effectively disables proxy)
`example.com`	Exact hostname
`.example.com`	All subdomains of example.com
`example.com:8080`	Specific host and port
`192.168.1.1`	Exact IP address
`[::1]`	IPv6 address
`[::1]:8080`	IPv6 address with port

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 Craft Agents:

macOS
Windows
Linux

One-time launch from terminal:

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

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 Craft Agents. 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.craft.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.craft.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\craft-agents\Craft Agents.exe"

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

Press Win + R, type sysdm.cpl, press Enter
Go to the Advanced tab → click Environment Variables
Under User variables, click New
Variable name: NODE_EXTRA_CA_CERTS
Variable value: C:\path\to\corporate-ca.pem
Click OK on all dialogs
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 craft-agents

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

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/@craft-agent/electron/main.log (macOS)

Configuration

CLI

​Configuration

​How It Works

​Proxy Authentication

​No Proxy Rules

​TLS-Intercepting Proxies (Corporate Firewalls)

​Symptoms

​Solution

​Obtaining the CA Certificate

​Troubleshooting

​”Fetch failed” on OAuth sign-in

​Proxy works for browsing but not for OAuth

​MCP servers fail to connect

​Proxy authentication fails

​Verifying proxy is active

Configuration

How It Works

Proxy Authentication

No Proxy Rules

TLS-Intercepting Proxies (Corporate Firewalls)

Symptoms

Solution

Obtaining the CA Certificate

Troubleshooting

”Fetch failed” on OAuth sign-in

Proxy works for browsing but not for OAuth

MCP servers fail to connect

Proxy authentication fails

Verifying proxy is active