Dynamic Proxy Switching

Switch proxies at runtime per BrowserContext without restarting BotBrowser sessions.

Prerequisites

BotBrowser ENT Tier3 license.
BotBrowser binary with a valid profile loaded via --bot-profile.
A running browser instance with at least one BrowserContext.

Quick Start

Use the CDP command BotBrowser.setBrowserContextProxy to change the proxy for an existing context:


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=socks5://user:pass@us-proxy.example.com:1080",
  ],
});
 
const ctx = await browser.createBrowserContext();
const page = await ctx.newPage();
const client = await browser.target().createCDPSession(); // must use browser-level session
 
// Switch to a UK proxy at runtime
await client.send("BotBrowser.setBrowserContextProxy", {
  browserContextId: ctx._contextId,
  proxyServer: "socks5://user:pass@uk-proxy.example.com:1080",
});
 
// Geo signals (timezone, locale, languages) are re-detected automatically
await page.goto("https://example.co.uk");
 
await browser.close();

How It Works

When you call BotBrowser.setBrowserContextProxy, BotBrowser:

Updates the proxy configuration for the specified BrowserContext.
Re-detects the new proxy’s exit IP (unless proxyIp is provided).
Re-configures timezone, locale, and language to match the new proxy location.
All subsequent network requests from that context use the new proxy.

Pages already loaded in the context continue to function. New navigations and network requests use the updated proxy.

CDP Command Parameters

Parameter	Required	Description
`browserContextId`	Yes	The ID of the BrowserContext to update.
`proxyServer`	Yes	Proxy URL with embedded credentials (e.g., `socks5://user:pass@host:port`).
`proxyIp`	No	The proxy’s exit IP. Skips auto-detection for faster geo configuration.
`proxyBypassList`	No	Semicolon-separated list of hosts to connect directly (e.g., `localhost;127.0.0.1`).
`proxyBypassRgx`	No	Regex pattern (RE2 syntax) for URLs that should connect directly.

Clearing the Proxy

To remove the proxy override and revert to the browser-level proxy (or direct connection):


await client.send("BotBrowser.clearBrowserContextProxy", {
  browserContextId: ctx._contextId,
});

Common Scenarios

Rotating proxies across regions

Switch between geographic regions within the same context, with automatic geo re-detection after each switch:


const client = await browser.target().createCDPSession(); // must use browser-level session
 
// Start with US proxy
await client.send("BotBrowser.setBrowserContextProxy", {
  browserContextId: ctx._contextId,
  proxyServer: "socks5://user:pass@us-proxy.example.com:1080",
  proxyIp: "203.0.113.1",
});
await page.goto("https://example.com");
 
// Switch to UK proxy
await client.send("BotBrowser.setBrowserContextProxy", {
  browserContextId: ctx._contextId,
  proxyServer: "socks5h://user:pass@uk-proxy.example.com:1080",
  proxyIp: "198.51.100.1",
});
await page.goto("https://example.co.uk");
 
// Switch to Japan proxy
await client.send("BotBrowser.setBrowserContextProxy", {
  browserContextId: ctx._contextId,
  proxyServer: "socks5://user:pass@jp-proxy.example.com:1080",
  proxyIp: "192.0.2.1",
});
await page.goto("https://example.co.jp");

Using proxyIp to skip detection

When you know the exit IP upfront, pass proxyIp to skip the IP detection step. This eliminates the one-time detection latency on the first navigation after each switch:


await client.send("BotBrowser.setBrowserContextProxy", {
  browserContextId: ctx._contextId,
  proxyServer: "socks5://user:pass@proxy.example.com:1080",
  proxyIp: "203.0.113.1", // Skip IP detection, configure geo instantly
});

Switching with proxy bypass rules

Apply selective routing when switching proxies. Some requests can connect directly while others go through the proxy:


await client.send("BotBrowser.setBrowserContextProxy", {
  browserContextId: ctx._contextId,
  proxyServer: "socks5://user:pass@proxy.example.com:1080",
  proxyBypassList: "localhost;127.0.0.1",
  proxyBypassRgx: "cdn\\.example\\.com|/static/",
});

Troubleshooting / FAQ

Problem	Solution
`setBrowserContextProxy` not found	The `BotBrowser` CDP domain is only available on browser-level sessions. Use `browser.target().createCDPSession()` (Puppeteer) or `browser.newBrowserCDPSession()` (Playwright) instead of `page.createCDPSession()`. Also ensure you have an ENT Tier3 license.
Geo signals not updating after switch	Geo re-detection happens on the next main-frame navigation. Navigate to a new page after switching.
Slow proxy switch	Pass `proxyIp` to skip IP auto-detection on each switch.
Old proxy still used for some requests	In-flight requests complete on the previous proxy. New requests use the updated proxy.

Next Steps

Proxy Configuration. Basic proxy setup and supported protocols.
Proxy and Geolocation. How auto-detection derives timezone, locale, and language.
Per-Context Proxy. Assign different proxies to different contexts at creation time.
Proxy Selective Routing. Selectively route requests through or around the proxy.
CLI Flags Reference. Complete list of all available flags.

Related documentation: Advanced Features | Per-Context Fingerprint | CDP Quick Reference

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