Proxy and VPN Configuration

You installed Claude Code, authenticated, and ran your first prompt. It hangs for thirty seconds, then throws ECONNREFUSED. Your corporate network requires all HTTPS traffic to go through a proxy, and Claude Code does not know about it. Half the developers on your team give up here.

This guide covers every networking scenario you will encounter in a corporate environment, from simple HTTP proxies to mTLS with custom certificate authorities.

What You Will Walk Away With

• Working Claude Code behind HTTP/HTTPS proxies
• Custom CA certificate configuration for corporate TLS inspection
• VPN-specific troubleshooting for split-tunnel and full-tunnel configurations
• Environment variable patterns that work across all Node.js-based tools

HTTP Proxy Configuration

Claude Code is a Node.js application and respects standard proxy environment variables.

Basic Proxy Setup

# Set for your current shell session
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

# Start Claude Code
claude

For persistent configuration, add these to your shell profile (~/.bashrc, ~/.zshrc, or ~/.profile):

# In ~/.zshrc or ~/.bashrc
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com,.internal"

Tip

Copy-paste proxy configuration for Claude Code settings:

Add to your user settings at ~/.claude/settings.json:

{
  "env": {
    "HTTP_PROXY": "http://proxy.company.com:8080",
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.company.com"
  }
}

This applies the proxy to every Claude Code session without modifying your shell environment.

Authenticated Proxies

If your proxy requires authentication:

export HTTPS_PROXY="http://username:password@proxy.company.com:8080"

For proxies using NTLM or Kerberos authentication, you typically need a local proxy tool like cntlm or px:

# Install and configure cntlm
brew install cntlm  # macOS

# Configure cntlm with your AD credentials
# Then point Claude Code at the local cntlm proxy
export HTTPS_PROXY="http://localhost:3128"

Custom CA Certificates

Many corporate networks use TLS inspection proxies with custom certificate authorities. Node.js does not use the system certificate store by default.

Adding Custom CA Certificates

# Point Node.js to your corporate CA bundle
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"

Tip

Copy-paste certificate configuration:

# Find your corporate CA certificate (common locations)
# macOS: Export from Keychain Access
# Linux: /etc/ssl/certs/ or /usr/local/share/ca-certificates/

# Set in your shell profile
export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/corporate-ca.pem"

# Or in Claude Code settings
# ~/.claude/settings.json
{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corporate-ca.pem"
  }
}

Extracting CA Certificates

On macOS, export from Keychain:

# Export all trusted root certificates
security find-certificate -a -p /Library/Keychains/System.keychain > /tmp/corporate-cas.pem
security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain >> /tmp/corporate-cas.pem

On Linux:

# Combine system certs with corporate cert
cat /etc/ssl/certs/ca-certificates.crt /path/to/corporate-ca.crt > /tmp/combined-cas.pem
export NODE_EXTRA_CA_CERTS="/tmp/combined-cas.pem"

Caution

Never set NODE_TLS_REJECT_UNAUTHORIZED=0 as a permanent solution. This disables all TLS verification and leaves you vulnerable to man-in-the-middle attacks. Always configure the proper CA certificates instead.

VPN Configurations

Split-Tunnel VPN

Split-tunnel VPNs route only corporate traffic through the VPN. Claude Code’s API calls go to api.anthropic.com, which typically routes through the public internet:

• If api.anthropic.com is not in your VPN’s route table, it works without proxy configuration
• If your VPN routes all traffic (full tunnel), you need the proxy setup above

Full-Tunnel VPN

Full-tunnel VPNs route all traffic through corporate infrastructure. You will almost certainly need:

1. Proxy configuration (for HTTP/HTTPS traffic)
2. Custom CA certificates (for TLS inspection)
3. DNS resolution for api.anthropic.com through corporate DNS

Troubleshooting VPN Issues

# Check if api.anthropic.com resolves
nslookup api.anthropic.com

# Check if you can reach the API endpoint
curl -v https://api.anthropic.com/v1/messages 2>&1 | head -30

# Check current proxy settings
env | grep -i proxy

# Test with Claude Code debug mode
claude --debug "api"

Tip

Copy-paste diagnostic script for proxy issues:

#!/bin/bash
echo "=== Proxy Environment ==="
env | grep -i proxy
echo ""
echo "=== CA Certificates ==="
echo "NODE_EXTRA_CA_CERTS: ${NODE_EXTRA_CA_CERTS:-not set}"
echo ""
echo "=== DNS Resolution ==="
nslookup api.anthropic.com 2>&1 | tail -5
echo ""
echo "=== Connection Test ==="
curl -s -o /dev/null -w "HTTP %{http_code} in %{time_total}s" https://api.anthropic.com/ 2>&1
echo ""

Managed Proxy Configuration

For organization-wide deployment, use managed settings to enforce proxy configuration:

{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "NO_PROXY": "localhost,127.0.0.1,.company.com",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corporate-ca.pem"
  }
}

Deploy this to the managed settings location for your platform. See Enterprise Integration for details on managed settings file locations.

When This Breaks

ECONNREFUSED after proxy setup: The proxy URL might be wrong. Test with curl -x http://proxy.company.com:8080 https://api.anthropic.com/. If curl works but Claude Code does not, check that your environment variables are exported and visible to the Claude Code process.

SSL certificate errors with proxy: Your proxy is likely doing TLS inspection and you need to configure NODE_EXTRA_CA_CERTS. Get the CA certificate from your IT department.

Proxy works for curl but not Claude Code: Node.js handles proxies differently from curl. Make sure you are using HTTPS_PROXY (not just https_proxy — though both should work, the uppercase version is more reliable across tools).

Timeouts behind VPN: Full-tunnel VPNs can add significant latency. If Claude Code times out, check whether the VPN is adding more than 2-3 seconds of RTT to api.anthropic.com.

What is Next

• LLM Gateway Setup — Route through cloud provider gateways instead of direct API access
• Enterprise Integration — Managed settings for organization-wide proxy deployment
• Monitoring and Costs — Verify telemetry data flows through your proxy