Proxy and VPN Configuration

Proxy and VPN Configuration

Many enterprise environments require proxy configurations or VPN connections. This guide covers how to configure Claude Code to work seamlessly in restricted network environments.

Understanding Network Restrictions

Note

Claude Code respects system-wide proxy settings but may need additional configuration for certain enterprise setups.

Common Enterprise Scenarios

HTTP/HTTPS Proxy

Forward all traffic through corporate proxy server for security and monitoring

SOCKS Proxy

Route traffic through SOCKS proxy for additional protocols and flexibility

VPN Required

Connect to corporate VPN before accessing internal resources or internet

Certificate Authentication

Use corporate certificates for proxy authentication and SSL inspection

Basic Proxy Configuration

Environment Variables

1. Set HTTP/HTTPS proxy

   # Linux/macOS
   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   export http_proxy=$HTTP_PROXY
   export https_proxy=$HTTPS_PROXY
   
   # Windows (Command Prompt)
   set HTTP_PROXY=http://proxy.company.com:8080
   set HTTPS_PROXY=http://proxy.company.com:8080
   
   # Windows (PowerShell)
   $env:HTTP_PROXY="http://proxy.company.com:8080"
   $env:HTTPS_PROXY="http://proxy.company.com:8080"

2. Configure no-proxy exceptions

   # Internal domains that shouldn't go through proxy
   export NO_PROXY=localhost,127.0.0.1,*.internal.company.com,10.0.0.0/8
   
   # Windows
   set NO_PROXY=localhost,127.0.0.1,*.internal.company.com,10.0.0.0/8

3. Verify configuration

   # Test proxy connectivity
   claude "Test my network configuration and verify:
   - Proxy settings are detected
   - Can reach external APIs
   - DNS resolution works
   - Certificate validation passes"

Authenticated Proxy

Basic Auth

# Include credentials in proxy URL
export HTTP_PROXY=http://username:password@proxy.company.com:8080
export HTTPS_PROXY=http://username:password@proxy.company.com:8080

# More secure: use encoded credentials
export HTTP_PROXY=http://$(echo -n username:password | base64)@proxy.company.com:8080

NTLM Auth

# For Windows NTLM authentication, use CNTLM
# Install cntlm proxy
sudo apt-get install cntlm  # Linux
brew install cntlm          # macOS

# Configure /etc/cntlm.conf
Username    your_username
Domain      CORPORATE
Proxy       proxy.company.com:8080
NoProxy     localhost, 127.0.0.*, 10.*, 192.168.*
Listen      3128

# Generate password hash
cntlm -H -u your_username -d CORPORATE

# Start cntlm
sudo cntlm -c /etc/cntlm.conf

# Point Claude Code to local proxy
export HTTP_PROXY=http://localhost:3128
export HTTPS_PROXY=http://localhost:3128

Kerberos

# For Kerberos authentication
# Ensure Kerberos is configured
kinit username@CORPORATE.REALM

# Use proxy with Kerberos support
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# May need to set additional Kerberos options
export KRB5_CONFIG=/etc/krb5.conf

SSL Certificate Management

Corporate CA Certificates

1. Export corporate certificates

   # Get certificate from IT department or export from browser
   # Usually in .crt, .pem, or .cer format

2. Install certificates system-wide

   Linux

   # Copy certificate to system store
   sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates
   
   # For RHEL/CentOS
   sudo cp corporate-ca.crt /etc/pki/ca-trust/source/anchors/
   sudo update-ca-trust

   macOS

   # Add to system keychain
   sudo security add-trusted-cert -d -r trustRoot \
     -k /Library/Keychains/System.keychain corporate-ca.crt
   
   # Or use Keychain Access GUI

   Windows

   # Run as Administrator
   Import-Certificate -FilePath "corporate-ca.crt" `
     -CertStoreLocation Cert:\LocalMachine\Root

3. Configure Node.js to use certificates

   # Point to certificate bundle
   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt
   
   # Or disable SSL verification (NOT recommended for production)
   export NODE_TLS_REJECT_UNAUTHORIZED=0

SSL Inspection Bypass

Caution

Only use these methods if approved by your security team. They may violate corporate policies.

# Temporary SSL bypass for testing
claude --no-verify-ssl "Your command here"

# Configure git to work with corporate proxy
git config --global http.proxy http://proxy.company.com:8080
git config --global https.proxy http://proxy.company.com:8080
git config --global http.sslVerify false  # Only if necessary

VPN Configuration

Split Tunnel VPN

Optimizing VPN Usage

# Check routing table to understand VPN impact
claude "Analyze my network routing:
- Show current routes
- Identify VPN interfaces
- Check which traffic goes through VPN
- Suggest optimizations for Claude Code"

# Configure Claude Code to use direct internet when possible
export CLAUDE_DIRECT_CONNECTION=true  # If supported

VPN Connection Scripts

1. Automated VPN connection

   vpn-connect.sh

   #!/bin/bash
   # Connect to VPN
   echo "Connecting to corporate VPN..."
   /opt/cisco/anyconnect/bin/vpn -s connect vpn.company.com << EOF
   username
   password
   y
   EOF
   
   # Wait for connection
   sleep 5
   
   # Verify connection
   if ip addr show | grep -q "vpn0"; then
     echo "VPN connected successfully"
   
     # Set proxy for VPN network
     export HTTP_PROXY=http://internal-proxy:8080
     export HTTPS_PROXY=http://internal-proxy:8080
   
     # Start Claude Code session
     claude "VPN connected, ready for work"
   else
     echo "VPN connection failed"
     exit 1
   fi

2. VPN disconnect cleanup

   vpn-disconnect.sh

   #!/bin/bash
   # Disconnect VPN
   /opt/cisco/anyconnect/bin/vpn disconnect
   
   # Clear proxy settings
   unset HTTP_PROXY
   unset HTTPS_PROXY
   
   echo "VPN disconnected, proxy settings cleared"

Advanced Proxy Scenarios

SOCKS Proxy Configuration

# For SOCKS5 proxy
export ALL_PROXY=socks5://proxy.company.com:1080
export all_proxy=$ALL_PROXY

# With authentication
export ALL_PROXY=socks5://username:password@proxy.company.com:1080

# SSH tunnel as SOCKS proxy
ssh -D 1080 -N jumphost.company.com
export ALL_PROXY=socks5://localhost:1080

PAC File Configuration

Proxy Auto-Configuration

// Example PAC file logic
function FindProxyForURL(url, host) {
  // Direct connection for internal sites
  if (isInNet(host, "10.0.0.0", "255.0.0.0") ||
      dnsDomainIs(host, ".internal.company.com")) {
    return "DIRECT";
  }

  // Use proxy for external sites
  return "PROXY proxy.company.com:8080";
}

# Use PAC file with Claude Code
export AUTO_PROXY=http://proxy.company.com/proxy.pac

# Parse PAC file manually if needed
claude "Parse this PAC file and extract:
- Proxy rules
- Direct connection domains
- Create equivalent environment variables"

Troubleshooting

Common Issues and Solutions

Connection Timeout

# Increase timeout values
export CLAUDE_TIMEOUT=300  # 5 minutes

# Test connectivity
claude "Debug my connection issues:
- Test proxy connectivity
- Check DNS resolution
- Verify SSL handshake
- Measure latency"

SSL Errors

# Debug SSL issues
openssl s_client -connect api.anthropic.com:443 \
  -proxy proxy.company.com:8080

# Check certificate chain
claude "Analyze SSL certificate chain:
- Show all certificates
- Verify corporate CA is trusted
- Check for expired certificates
- Suggest fixes"

Authentication Failed

# Debug proxy authentication
curl -v -x http://proxy.company.com:8080 https://api.anthropic.com

# Test with different auth methods
claude "Test proxy authentication:
- Try basic auth
- Test NTLM if Windows domain
- Check Kerberos ticket
- Verify credentials"

Diagnostic Commands

1. Network diagnostics

   claude "Run comprehensive network diagnostics:
   - Show all network interfaces
   - Display routing table
   - Check DNS servers
   - Test proxy connectivity
   - Verify certificate stores
   - Check environment variables"

2. Proxy test script

   claude "Create a proxy test script that:
   - Tests HTTP/HTTPS connectivity
   - Verifies proxy authentication
   - Checks SSL certificate validation
   - Measures response times
   - Tests Claude Code API access"

3. Environment validation

   claude "Validate my environment for Claude Code:
   - Check all proxy variables
   - Verify certificate configuration
   - Test API endpoints
   - Check for conflicts
   - Generate report"

Performance Optimization

Caching Proxy Setup

Local Caching Proxy

# Install Squid as local caching proxy
sudo apt-get install squid

# Configure Squid to cache Claude Code requests
claude "Configure Squid proxy for:
- Cache API responses where appropriate
- Forward to corporate proxy
- Handle SSL bumping if needed
- Optimize for Claude Code usage"

Connection Pooling

# Configure connection reuse
export CLAUDE_KEEP_ALIVE=true
export CLAUDE_MAX_SOCKETS=10

# For better performance through proxy
export HTTP_KEEP_ALIVE=true
export HTTPS_KEEP_ALIVE=true

Security Best Practices

Security Considerations

• Never hardcode credentials in scripts
• Use secure credential storage (keychain, credential manager)
• Regularly rotate proxy passwords
• Monitor for unusual network activity
• Follow corporate security policies

Secure Credential Management

Linux

# Use secret-tool for credential storage
echo -n "proxy-password" | secret-tool store \
  --label="Corporate Proxy" \
  service proxy \
  username myusername

# Retrieve in script
PROXY_PASS=$(secret-tool lookup service proxy username myusername)
export HTTP_PROXY="http://myusername:${PROXY_PASS}@proxy.company.com:8080"

macOS

# Store in Keychain
security add-generic-password \
  -a "myusername" \
  -s "Corporate Proxy" \
  -w "proxy-password"

# Retrieve in script
PROXY_PASS=$(security find-generic-password \
  -a "myusername" \
  -s "Corporate Proxy" \
  -w)

Windows

# Store in Credential Manager
cmdkey /add:proxy.company.com /user:myusername /pass:proxy-password

# Use in scripts with stored credentials

Next Steps

Master more enterprise features:

• LLM Gateway for custom endpoints
• Enterprise Integration for corporate tools
• Monitoring Costs for usage tracking

Remember: Proxy configuration can be complex in enterprise environments. Always work with your IT team to ensure compliance with security policies while maintaining productivity with Claude Code.