Proxy Support

Proxy configuration for geo-testing, rate limiting avoidance, and corporate environments.

Related: commands.md for global options, SKILL.md for quick start.

Contents

• Basic Proxy Configuration
• Authenticated Proxy
• SOCKS Proxy
• Proxy Bypass
• Common Use Cases
• Verifying Proxy Connection
• Troubleshooting
• Best Practices

Basic Proxy Configuration

Use the --proxy flag or set proxy via environment variable:

# Via CLI flag
agent-browser --proxy "http://proxy.example.com:8080" open https://example.com

# Via environment variable
export HTTP_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com

# HTTPS proxy
export HTTPS_PROXY="https://proxy.example.com:8080"
agent-browser open https://example.com

# Both
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com

Authenticated Proxy

For proxies requiring authentication:

# Include credentials in URL
export HTTP_PROXY="http://username:password@proxy.example.com:8080"
agent-browser open https://example.com

SOCKS Proxy

# SOCKS5 proxy
export ALL_PROXY="socks5://proxy.example.com:1080"
agent-browser open https://example.com

# SOCKS5 with auth
export ALL_PROXY="socks5://user:pass@proxy.example.com:1080"
agent-browser open https://example.com

Proxy Bypass

Skip proxy for specific domains using --proxy-bypass or NO_PROXY:

# Via CLI flag
agent-browser --proxy "http://proxy.example.com:8080" --proxy-bypass "localhost,*.internal.com" open https://example.com

# Via environment variable
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"
agent-browser open https://internal.company.com  # Direct connection
agent-browser open https://external.com          # Via proxy

Common Use Cases

Geo-Location Testing

#!/bin/bash
# Test site from different regions using geo-located proxies

PROXIES=(
    "http://us-proxy.example.com:8080"
    "http://eu-proxy.example.com:8080"
    "http://asia-proxy.example.com:8080"
)

for proxy in "${PROXIES[@]}"; do
    export HTTP_PROXY="$proxy"
    export HTTPS_PROXY="$proxy"

    region=$(echo "$proxy" | grep -oP '^\w+-\w+')
    echo "Testing from: $region"

    agent-browser --session "$region" open https://example.com
    agent-browser --session "$region" screenshot "./screenshots/$region.png"
    agent-browser --session "$region" close
done

Rotating Proxies for Scraping

#!/bin/bash
# Rotate through proxy list to avoid rate limiting

PROXY_LIST=(
    "http://proxy1.example.com:8080"
    "http://proxy2.example.com:8080"
    "http://proxy3.example.com:8080"
)

URLS=(
    "https://site.com/page1"
    "https://site.com/page2"
    "https://site.com/page3"
)

for i in "${!URLS[@]}"; do
    proxy_index=$((i % ${#PROXY_LIST[@]}))
    export HTTP_PROXY="${PROXY_LIST[$proxy_index]}"
    export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}"

    agent-browser open "${URLS[$i]}"
    agent-browser get text body > "output-$i.txt"
    agent-browser close

    sleep 1  # Polite delay
done

Corporate Network Access

#!/bin/bash
# Access internal sites via corporate proxy

export HTTP_PROXY="http://corpproxy.company.com:8080"
export HTTPS_PROXY="http://corpproxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"

# External sites go through proxy
agent-browser open https://external-vendor.com

# Internal sites bypass proxy
agent-browser open https://intranet.company.com

Verifying Proxy Connection

# Check your apparent IP
agent-browser open https://httpbin.org/ip
agent-browser get text body
# Should show proxy's IP, not your real IP

Troubleshooting

Proxy Connection Failed

# Test proxy connectivity first
curl -x http://proxy.example.com:8080 https://httpbin.org/ip

# Check if proxy requires auth
export HTTP_PROXY="http://user:pass@proxy.example.com:8080"

SSL/TLS Errors Through Proxy

Some proxies perform SSL inspection with a custom CA certificate. Trust only that CA:

# Recommended: trust the proxy's CA certificate
agent-browser --ca-cert /etc/ssl/certs/proxy-ca.crt open https://example.com

# Via environment variable
export AGENT_BROWSER_CA_CERT=/etc/ssl/certs/proxy-ca.crt
agent-browser open https://example.com

On Linux, --ca-cert imports the certificate or PEM bundle into an isolated NSS database used only by that locally launched Chromium process. Certificate hostname, validity period, and unrelated authority verification stay enabled. Later commands retain the CA when they omit the flag. Use --no-ca-cert to clear it. Different certificate content or an explicit clear relaunches Chromium without restarting the daemon, while the same content from any path reuses the browser. agent-browser install --with-deps installs the required certutil; otherwise install libnss3-tools on Debian/Ubuntu or nss-tools on RPM Linux.

The initial implementation does not support --profile, --cdp, --auto-connect, providers, Lightpanda, macOS, or Windows. Use --ignore-https-errors only when a broad bypass is the intended contract.

Without the CA certificate on hand, fall back to ignoring every certificate error:

# For testing only - not recommended for production
agent-browser open https://example.com --ignore-https-errors

Slow Performance

# Use proxy only when necessary
export NO_PROXY="*.cdn.com,*.static.com"  # Direct CDN access

Best Practices

1. Use environment variables - Don't hardcode proxy credentials
2. Set NO_PROXY appropriately - Avoid routing local traffic through proxy
3. Test proxy before automation - Verify connectivity with simple requests
4. Handle proxy failures gracefully - Implement retry logic for unstable proxies
5. Rotate proxies for large scraping jobs - Distribute load and avoid bans