/agent-browser

Proxy Support

Proxy configuration for geo-testing, privacy, and corporate environments.

Related: commands.md for full function reference, SKILL.md for quick start.

Contents

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

Basic Proxy Configuration

Set proxy when opening a session:

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com",
  "proxy_url": "http://proxy.example.com:8080"
}' | jq -r '.session_id')

All traffic for this session routes through the proxy.

Authenticated Proxy

For proxies requiring username/password:

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://example.com",
  "proxy_url": "http://proxy.example.com:8080",
  "proxy_username": "myuser",
  "proxy_password": "mypassword"
}' | jq -r '.session_id')

Common Use Cases

Geo-Location Testing

Test how your site appears from different regions:

#!/bin/bash
# Test from multiple regions

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

for entry in "${PROXIES[@]}"; do
  REGION="${entry%%|*}"
  PROXY="${entry##*|}"

  echo "Testing from: $REGION"

  SESSION=$(belt app run agent-browser --function open --session new --input '{
    "url": "https://mysite.com",
    "proxy_url": "'"$PROXY"'"
  }' | jq -r '.session_id')

  # Take screenshot
  belt app run agent-browser --function screenshot --session $SESSION --input '{
    "full_page": true
  }' > "${REGION}-screenshot.json"

  # Get page content
  RESULT=$(belt app run agent-browser --function snapshot --session $SESSION --input '{}')
  echo $RESULT | jq '.elements_text' > "${REGION}-elements.txt"

  belt app run agent-browser --function close --session $SESSION --input '{}'
done

echo "Geo-testing complete"

Rate Limit Avoidance

Rotate proxies for web scraping:

#!/bin/bash
# Rotate through proxy list

PROXIES=(
  "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
  # Rotate proxy
  PROXY_INDEX=$((i % ${#PROXIES[@]}))
  PROXY="${PROXIES[$PROXY_INDEX]}"
  URL="${URLS[$i]}"

  echo "Fetching $URL via proxy $((PROXY_INDEX + 1))"

  SESSION=$(belt app run agent-browser --function open --session new --input '{
    "url": "'"$URL"'",
    "proxy_url": "'"$PROXY"'"
  }' | jq -r '.session_id')

  # Extract data
  RESULT=$(belt app run agent-browser --function execute --session $SESSION --input '{
    "code": "document.body.innerText"
  }')
  echo $RESULT | jq -r '.result' > "page-$i.txt"

  belt app run agent-browser --function close --session $SESSION --input '{}'

  # Polite delay
  sleep 1
done

Corporate Network Access

Access sites through corporate proxy:

# Use corporate proxy for external sites
SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://external-vendor.com",
  "proxy_url": "http://corpproxy.company.com:8080",
  "proxy_username": "'"$CORP_USER"'",
  "proxy_password": "'"$CORP_PASS"'"
}' | jq -r '.session_id')

Privacy and Anonymity

Route through privacy-focused proxy:

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://whatismyip.com",
  "proxy_url": "socks5://privacy-proxy.example.com:1080"
}' | jq -r '.session_id')

Proxy Types

HTTP/HTTPS Proxy

{"proxy_url": "http://proxy.example.com:8080"}
{"proxy_url": "https://proxy.example.com:8080"}

SOCKS5 Proxy

{"proxy_url": "socks5://proxy.example.com:1080"}

With Authentication

{
  "proxy_url": "http://proxy.example.com:8080",
  "proxy_username": "user",
  "proxy_password": "pass"
}

Verifying Proxy Connection

Check that traffic routes through proxy:

SESSION=$(belt app run agent-browser --function open --session new --input '{
  "url": "https://httpbin.org/ip",
  "proxy_url": "http://proxy.example.com:8080"
}' | jq -r '.session_id')

# Get the IP shown
RESULT=$(belt app run agent-browser --function execute --session $SESSION --input '{
  "code": "document.body.innerText"
}')
echo "IP via proxy: $(echo $RESULT | jq -r '.result')"

belt app run agent-browser --function close --session $SESSION --input '{}'

The IP should be the proxy's IP, not your real IP.

Troubleshooting

Connection Failed

Error: Failed to open URL: net::ERR_PROXY_CONNECTION_FAILED

Solutions:

1. Verify proxy URL is correct
2. Check proxy is running and accessible
3. Confirm port is correct
4. Test proxy with curl: curl -x http://proxy:8080 https://example.com

Authentication Failed

Error: 407 Proxy Authentication Required

Solutions:

1. Verify username/password are correct
2. Check if proxy requires different auth method
3. Ensure credentials don't contain special characters that need escaping

SSL Errors

Some proxies perform SSL inspection. If you see certificate errors:

# The browser should handle most SSL proxies automatically
# If issues persist, verify proxy SSL certificate is valid

Slow Performance

Solutions:

1. Choose proxy closer to target site
2. Use faster proxy provider
3. Reduce number of requests per session

Best Practices

1. Use Environment Variables

# Good: Credentials in env vars
'{"proxy_url": "'"$PROXY_URL"'", "proxy_username": "'"$PROXY_USER"'"}'

# Bad: Hardcoded
'{"proxy_url": "http://user:pass@proxy.com:8080"}'

2. Test Proxy Before Automation

# Verify proxy works
curl -x "$PROXY_URL" https://httpbin.org/ip

3. Handle Proxy Failures

# Retry with different proxy on failure
for PROXY in "${PROXIES[@]}"; do
  SESSION=$(belt app run agent-browser --function open --session new --input '{
    "url": "'"$URL"'",
    "proxy_url": "'"$PROXY"'"
  }' 2>&1)

  if echo "$SESSION" | jq -e '.session_id' > /dev/null 2>&1; then
    SESSION_ID=$(echo $SESSION | jq -r '.session_id')
    break
  fi
  echo "Proxy $PROXY failed, trying next..."
done

4. Respect Rate Limits

Even with proxies, be a good citizen:

# Add delays between requests
'{"action": "wait", "wait_ms": 1000}'

5. Log Proxy Usage

For debugging, log which proxy was used:

echo "$(date): Using proxy $PROXY for $URL" >> proxy.log