Proxy Configuration

Configure HTTP/SOCKS proxies correctly for stable browser identity and network privacy.

Prerequisites

• BotBrowser binary installed on your system. See INSTALLATION.md for platform-specific setup.
• Node.js 18 or later (for Playwright/Puppeteer examples).
• A profile file (.enc for production, .json for local development).
• A proxy server with HTTP, HTTPS, SOCKS5, or SOCKS5H support.

Quick Start

Pass your proxy directly in the browser launch arguments using --proxy-server:

import { chromium } from "playwright-core";
 
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
  ],
});
 
const page = await browser.newPage();
await page.goto("https://example.com");
console.log("Page title:", await page.title());
await browser.close();

BotBrowser auto-detects timezone, locale, and language from the proxy exit IP. No additional configuration is needed for geographic consistency.

How It Works

BotBrowser extends the standard --proxy-server flag with two key enhancements:

1. Embedded credentials. Standard browsers require separate authentication. BotBrowser accepts user:pass@host:port directly in the proxy URL, eliminating the need for page.authenticate() or framework proxy options.

2. Automatic geo-detection. When a proxy is configured via --proxy-server, BotBrowser detects the proxy’s exit IP and configures timezone, locale, and language to match. This happens before the first page loads. See Proxy and Geolocation for the full pipeline.

Supported Protocols

Credential Format

Embed username and password directly in the proxy URL:

protocol://username:password@hostname:port

Examples:

# HTTP with credentials
--proxy-server=http://myuser:mypass@proxy.example.com:8080
 
# SOCKS5 with credentials
--proxy-server=socks5://myuser:mypass@proxy.example.com:1080
 
# SOCKS5H with credentials (DNS resolved through the proxy)
--proxy-server=socks5h://myuser:mypass@proxy.example.com:1080

Structured Usernames

Many proxy providers encode routing information in the username using commas or pipes. BotBrowser supports these formats:

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

Common Scenarios

Why use —proxy-server instead of framework proxy options

Always configure the proxy through --proxy-server in the browser launch arguments, not through Playwright’s proxy option or Puppeteer’s page.authenticate().

// Correct: BotBrowser handles proxy and auto-detects geo info
const browser = await chromium.launch({
  executablePath: BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    `--bot-profile=${BOT_PROFILE_PATH}`,
    "--proxy-server=http://user:pass@proxy.example.com:8080",
  ],
});
 
// Avoid: Playwright's built-in proxy skips BotBrowser's geo-detection
const browser = await chromium.launch({
  proxy: { server: "http://proxy.example.com:8080" }, // Not recommended
});

Using --proxy-server ensures BotBrowser can detect the proxy’s geographic location and configure timezone, locale, and language automatically. Framework proxy options operate at a different layer and do not trigger this detection.

Playwright example with SOCKS5

import { chromium } from "playwright-core";
 
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
  ],
});
 
const page = await browser.newPage();
await page.addInitScript(() => {
  delete window.__playwright__binding__;
  delete window.__pwInitScripts;
});
 
await page.goto("https://example.com");
await browser.close();

Puppeteer example with HTTP proxy

const puppeteer = require("puppeteer-core");
 
const browser = await puppeteer.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  defaultViewport: null,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=http://user:pass@proxy.example.com:8080",
  ],
});
 
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

Using SOCKS5H for remote DNS resolution

When privacy requires that DNS queries also go through the proxy tunnel, use socks5h://. This prevents DNS queries from leaking to your local resolver.

--proxy-server=socks5h://user:pass@proxy.example.com:1080

With socks5h, the proxy server resolves hostnames, so the target domain name is never visible to your local DNS resolver.

Troubleshooting / FAQ

Next Steps

• Proxy and Geolocation. How BotBrowser auto-detects geographic signals from your proxy IP.
• Per-Context Proxy. Assign different proxies to different BrowserContexts.
• Dynamic Proxy Switching. Change proxy at runtime without restarting.
• WebRTC Leak Prevention. Protect against IP disclosure through WebRTC.
• DNS Leak Prevention. Prevent DNS queries from leaking outside the proxy tunnel.
• CLI Flags Reference. Complete list of all available flags.

Related documentation: CLI Flags Reference | Advanced Features | Getting Started with Playwright

Legal Disclaimer & Terms of Use  • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.