Proxy Configuration Guide for Cloud Browser Automation

Introduction

Proxies are the foundation of location-based automation. They determine your IP address, influence geographic identity signals, and are the first thing detection systems check. Choosing the right proxy type and configuring it correctly is essential for successful automation.

Proxy Types

HTTP/HTTPS Proxies

The simplest proxy type, forwarding HTTP traffic:

const browser = await puppeteer.connect({
  browserWSEndpoint:
    'wss://bots.win/ws?apiKey=YOUR_API_KEY&proxy=http://user:pass@proxy:8080',
});

Limitations: HTTP proxies do not support UDP traffic, meaning WebRTC STUN requests may bypass the proxy.

SOCKS5 Proxies

SOCKS5 supports both TCP and UDP:

socks5://user:pass@proxy:1080

Important: Standard SOCKS5 resolves DNS locally, which can leak your real DNS servers.

SOCKS5H Proxies

SOCKS5H (SOCKS5 with remote DNS resolution) is the recommended type:

const browser = await puppeteer.connect({
  browserWSEndpoint:
    'wss://bots.win/ws?apiKey=YOUR_API_KEY&proxy=socks5h://user:pass@proxy:1080',
});

Advantages:

• DNS resolved at the proxy (no DNS leak)
• UDP traffic tunneled (WebRTC protection)
• Full traffic encapsulation

Residential Proxies

Residential proxies use IP addresses assigned to real ISPs, making them appear as normal household connections:

// Sticky session (same IP for duration)
const browser = await puppeteer.connect({
  browserWSEndpoint:
    'wss://bots.win/ws?apiKey=YOUR_API_KEY&proxy=socks5h://user-session-abc123:pass@residential:1080',
});

Use cases: When datacenter IPs are blocked or when you need to appear as a residential user.

Geographic Targeting

By Country

Most proxy providers support country targeting:

// US proxy
const usProxy = 'socks5h://user-country-us:pass@proxy:1080';

// Germany proxy
const deProxy = 'socks5h://user-country-de:pass@proxy:1080';

// Japan proxy
const jpProxy = 'socks5h://user-country-jp:pass@proxy:1080';

By City

For more precise targeting:

// New York proxy
const nyProxy = 'socks5h://user-country-us-city-newyork:pass@proxy:1080';

Proxy Authentication

URL-Embedded Credentials

The simplest method, supported by all proxy types:

socks5h://username:password@host:port

Special Characters in Passwords

URL-encode special characters in proxy credentials:

// Password contains @: encode as %40
const proxy = 'socks5h://user:p%40ssword@proxy:1080';

// Password contains :: encode as %3A
const proxy = 'socks5h://user:p%3Assword@proxy:1080';

Proxy Rotation

Per-Session Rotation

Use a different proxy for each browser session:

const proxies = [
  'socks5h://user:pass@us-1:1080',
  'socks5h://user:pass@us-2:1080',
  'socks5h://user:pass@us-3:1080',
];

let proxyIndex = 0;

async function createSession() {
  const proxy = proxies[proxyIndex % proxies.length];
  proxyIndex++;

  return puppeteer.connect({
    browserWSEndpoint:
      `wss://bots.win/ws?apiKey=YOUR_API_KEY&proxy=${encodeURIComponent(proxy)}`,
  });
}

Sticky Sessions

For workflows requiring IP consistency across multiple requests:

// Use a session ID with your proxy provider for IP stickiness
const sessionId = `session-${Date.now()}`;
const proxy = `socks5h://user-session-${sessionId}:pass@rotating-proxy:1080`;

Verification

Always verify proxy configuration:

const page = await browser.newPage();
await page.goto('https://api.ipify.org?format=json');
const ip = await page.evaluate(() => document.body.textContent);
console.log('Session IP:', JSON.parse(ip).ip);

Best Practices

1. Use SOCKS5H to prevent DNS leaks
2. Match proxy location to profile - A US profile should use a US proxy
3. Use residential proxies when datacenter IPs are blocked
4. URL-encode special characters in proxy credentials
5. Verify proxy IP before starting automation
6. Use sticky sessions for workflows requiring IP consistency
7. Monitor proxy health - Slow or failed proxies should be rotated out