Browser Proxy Configuration: SOCKS5, HTTP, and HTTPS Guide

Introduction

A fingerprint profile alone is not enough for a consistent browser identity. Your IP address, DNS behavior, and geographic metadata must all align with the identity your profile presents. If your profile says "Windows user in Berlin" but your IP resolves to a data center in Virginia, the inconsistency is obvious.

BotBrowser provides enhanced proxy support built directly into the browser engine. Unlike standard Chromium, BotBrowser accepts embedded credentials in proxy URLs, auto-derives geographic settings from your proxy IP, and supports SOCKS5, SOCKS5H, HTTP, and HTTPS protocols. This guide covers every aspect of proxy configuration, from basic setup to advanced selective routing.

Privacy Impact

Without a properly configured proxy, your real IP address is visible to every site you visit. IP addresses reveal your ISP, approximate physical location, and can be correlated across sessions to build a persistent tracking profile.

Even when using a proxy, misconfigurations can undermine your privacy. DNS queries may leak outside the proxy tunnel, revealing your browsing activity to your ISP. WebRTC ICE candidates may expose your real IP through STUN requests that travel outside the proxy path. Timezone and locale mismatches between your stated identity and your IP's geolocation create inconsistencies that tracking systems can flag.

BotBrowser addresses all of these concerns in a unified configuration model. When you set --proxy-server, BotBrowser automatically detects the proxy's public IP and derives timezone, locale, and language settings to match. This means a single flag can align your entire geographic identity.

Technical Background

How Browser Proxying Works

When a browser uses a proxy, HTTP and HTTPS traffic is forwarded through the proxy server instead of connecting directly to the destination. The destination sees the proxy's IP address, not yours.

Different proxy protocols handle this differently:

SOCKS5 operates at the transport layer (Layer 5). It forwards raw TCP connections and optionally handles DNS resolution on the proxy side (SOCKS5H). SOCKS5 supports both TCP and UDP traffic, making it the most versatile protocol for privacy.

HTTP proxies use the CONNECT method to establish a tunnel for HTTPS traffic. The proxy sees the destination hostname but not the encrypted content. HTTP proxies do not handle UDP traffic.

HTTPS proxies encrypt the connection between your browser and the proxy server itself. This prevents your ISP from seeing which proxy commands you send, adding a layer of confidentiality to the proxy connection.

Credential Handling in Standard Chromium vs. BotBrowser

Standard Chromium's --proxy-server flag accepts only the proxy address without credentials. Authentication requires separate handling through system prompts or framework-specific APIs like page.authenticate(). This is inconvenient and can interfere with BotBrowser's automatic geographic detection.

BotBrowser extends --proxy-server to accept credentials embedded directly in the URL:

protocol://username:password@host:port

This eliminates the need for separate authentication steps and keeps all proxy configuration in a single flag.

Supported Proxy Types and Configuration

BotBrowser supports four proxy protocols through the --proxy-server flag:

Protocol	URL Format	Use Case
SOCKS5	socks5://user:pass@host:port	General purpose, TCP traffic
SOCKS5H	socks5h://user:pass@host:port	DNS resolution stays within tunnel
HTTP	http://user:pass@host:port	Widely available, HTTP/HTTPS traffic
HTTPS	https://user:pass@host:port	Encrypted proxy connection

SOCKS5 vs. SOCKS5H

The difference between socks5:// and socks5h:// is important. With socks5://, DNS resolution happens locally on your machine before the connection is sent through the proxy. With socks5h://, the hostname is sent to the proxy server, which resolves DNS on your behalf. For privacy, socks5h:// is the better choice because it prevents DNS queries from leaking to your local resolver.

Structured Proxy Usernames

Some proxy providers encode routing instructions inside the username using separators like commas or pipes. BotBrowser supports these structured usernames:

--proxy-server=socks5://user_abc,type_mobile,country_GB,session_1234:password@portal.proxy.example.com:1080

This is common with residential proxy providers that route traffic based on parameters embedded in the credentials.

BotBrowser's Approach to Proxy Integration

Automatic Geographic Alignment

When BotBrowser connects through a proxy, it detects the proxy's public IP and automatically configures:

• Timezone: Derived from the IP's geolocation
• Locale: Matched to the proxy's country
• Languages: Set based on the proxy's region
• Geolocation: Coordinates approximated from the IP

This means a basic launch with just --proxy-server already produces a geographically consistent identity:

chrome --bot-profile="/path/to/profile.enc" \
       --proxy-server=socks5://user:pass@de-proxy:1080

BotBrowser will detect the German IP and set timezone to Europe/Berlin, locale to de-DE, and languages to de-DE,de,en automatically.

Manual Geographic Overrides

When you need specific geographic settings that differ from what the IP suggests, use the override flags:

chrome --bot-profile="/path/to/profile.enc" \
       --proxy-server=socks5://user:pass@proxy:1080 \
       --bot-config-timezone=America/New_York \
       --bot-config-locale=en-US \
       --bot-config-languages=en-US,en \
       --bot-config-location=40.7128,-74.0060

CLI flags carry the highest configuration priority and override both profile settings and auto-detected values.

Skipping IP Lookup with --proxy-ip

If you already know your proxy's public IP, you can skip the per-page IP lookup with the --proxy-ip flag (ENT Tier1):

chrome --bot-profile="/path/to/profile.enc" \
       --proxy-server=socks5://user:pass@proxy:1080 \
       --proxy-ip="203.0.113.1"

This eliminates the IP detection request on each page load, improving navigation speed.

Selective Proxy Routing with --proxy-bypass-rgx

The --proxy-bypass-rgx flag (PRO) lets you route specific URLs directly instead of through the proxy. This is useful for reducing proxy bandwidth on static assets:

chrome --bot-profile="/path/to/profile.enc" \
       --proxy-server=socks5://user:pass@proxy:1080 \
       --proxy-bypass-rgx="\.(js|css|png|jpg|svg)(\?|$)"

The pattern uses RE2 regex syntax and matches against both hostname and full URL path.

Important for JavaScript usage: do not include shell quotes inside the value:

// Correct
launchArgs.push('--proxy-bypass-rgx=\\.js($|\\?)');

// Wrong - quotes become part of the regex
launchArgs.push('--proxy-bypass-rgx="\\.js$"');

Configuration and Usage

Basic Playwright Setup

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--proxy-server=socks5://user:pass@proxy-host:1080',
    ],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Puppeteer Setup with Geographic Overrides

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--proxy-server=socks5://user:pass@de-proxy:1080',
      '--bot-config-timezone=Europe/Berlin',
      '--bot-config-locale=de-DE',
      '--bot-config-languages=de-DE,de,en',
    ],
    headless: true,
    defaultViewport: null,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Common Region Configurations

Region	Timezone	Locale	Languages
US East	America/New_York	en-US	en-US,en
US West	America/Los_Angeles	en-US	en-US,en
UK	Europe/London	en-GB	en-GB,en
Germany	Europe/Berlin	de-DE	de-DE,de,en
Japan	Asia/Tokyo	ja-JP	ja,en
Brazil	America/Sao_Paulo	pt-BR	pt-BR,pt,en
South Korea	Asia/Seoul	ko-KR	ko-KR,ko,en

Custom IP Detection Service

If you run your own IP detection endpoint, configure it with --bot-ip-service:

chrome --bot-profile="/path/to/profile.enc" \
       --proxy-server=socks5://user:pass@proxy:1080 \
       --bot-ip-service="https://ip.example.com"

You can provide multiple endpoints as a comma-separated list. BotBrowser races them and uses the fastest response:

--bot-ip-service="https://ip1.example.com,https://ip2.example.com"

Verification

After launching BotBrowser with a proxy, verify your configuration:

const page = await context.newPage();

// Check public IP
await page.goto('https://httpbin.org/ip');
const ipData = await page.textContent('body');
console.log('Public IP:', ipData);

// Check timezone
const tz = await page.evaluate(() =>
  Intl.DateTimeFormat().resolvedOptions().timeZone
);
console.log('Timezone:', tz);

// Check language
const lang = await page.evaluate(() => navigator.language);
console.log('Language:', lang);

// Check locale
const locale = await page.evaluate(() =>
  Intl.NumberFormat().resolvedOptions().locale
);
console.log('Locale:', locale);

Confirm that:

1. The IP matches your proxy's expected address
2. Timezone aligns with the proxy's geographic region
3. Language and locale are consistent with the timezone
4. No DNS leaks are visible (see the DNS Leak Prevention guide)

Best Practices

1. Use SOCKS5H for DNS privacy. The socks5h:// protocol resolves DNS through the proxy, preventing DNS queries from reaching your local ISP.

2. Let BotBrowser auto-detect geography. Unless you need specific overrides, the automatic IP-based detection produces consistent results with less configuration.

3. URL-encode special characters in passwords. Characters like @, #, and % must be encoded. For example, p@ss becomes p%40ss.

4. Combine with --bot-local-dns. For maximum DNS privacy, use the local DNS resolver alongside your proxy configuration.

5. Test with curl first. Before configuring BotBrowser, verify proxy connectivity: curl --proxy socks5://user:pass@host:port https://httpbin.org/ip.

6. Use --proxy-ip when the IP is known. This eliminates per-page lookup overhead and speeds up navigation.

Frequently Asked Questions

What proxy protocol should I use? SOCKS5H is recommended for most use cases. It supports TCP traffic, handles DNS resolution through the proxy, and works with the widest range of proxy providers.

Can I use a proxy that requires IP whitelisting? Yes. Ensure your machine's IP is whitelisted with the proxy provider, then use the proxy URL without credentials if the provider authenticates by IP.

Does BotBrowser support proxy chaining? BotBrowser connects to the proxy specified in --proxy-server. If you need proxy chaining, configure it on the proxy infrastructure side.

Why does my timezone not match my proxy location? If you set --bot-config-timezone manually, it overrides automatic detection. Remove the manual override to let BotBrowser derive timezone from the proxy IP.

Can I use different proxies for different tabs? Yes. Use Playwright's browser.newContext({ proxy: ... }) to assign different proxies per context. See Dynamic Proxy Switching for details.

What happens if the proxy connection fails? BotBrowser will not fall back to a direct connection. If the proxy is unreachable, page loads will fail, which is the safer behavior for privacy.

How do I handle proxy rotation? Create a new browser context for each proxy rotation. Closing the old context and opening a new one with a different proxy server is the cleanest approach. See Dynamic Proxy Switching.

Summary

Proxy configuration is the network foundation of a consistent browser identity. BotBrowser simplifies proxy setup with embedded credentials, automatic geographic alignment, and support for SOCKS5, SOCKS5H, HTTP, and HTTPS protocols. Combined with fingerprint profiles, proxy configuration ensures your IP, timezone, locale, and language all tell the same story.

For multi-proxy workflows, see Dynamic Proxy Switching. For preventing DNS and WebRTC leaks alongside your proxy, see DNS Leak Prevention and WebRTC Leak Prevention.