Browserless External Proxy Setup

Browserless can run a browser session while an external proxy supplies the network route. The useful boundary is explicit: Browserless handles the remote browser, the externalProxyServer option carries the upstream proxy URL, and your application decides whether the returned output is valid. Session creation alone cannot prove that the proxy authenticated or that the target accepted the request.

Route a REST request through an external proxy

Browserless documents externalProxyServer as a URL parameter. URL-encode the proxy URL, keep the Browserless token and proxy credentials in server-side secrets, and avoid printing the constructed endpoint.

const token = process.env.BROWSERLESS_TOKEN!;
const proxyUrl = process.env.PROXY_URL!;
const endpoint = new URL("https://production-sfo.browserless.io/content");
endpoint.search = new URLSearchParams({
  token,
  externalProxyServer: proxyUrl,
}).toString();

const response = await fetch(endpoint, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: process.env.TARGET_URL ?? "https://example.com/" }),
  signal: AbortSignal.timeout(30_000),
});
const html = await response.text();
const marker = process.env.EXPECTED_MARKER ?? "Example Domain";
const validOutput = response.ok && html.includes(marker);

console.log(JSON.stringify({
  status: response.status,
  bytes: Buffer.byteLength(html),
  validOutput,
}));
if (!validOutput) throw new Error("Browserless output failed validation");

The endpoint above records only the response status, size and validation result. It does not claim that a particular exit IP or country was used. Verify that separately with an endpoint you operate or explicitly trust. Browserless documents external proxy access for paid cloud plans, and the external route is separate from Browserless’s built-in residential or datacenter proxy units.

Use the same route from Puppeteer

The same Browserless boundary works when you connect with Puppeteer. The official example passes the URL-encoded proxy as externalProxyServer in the WebSocket endpoint, then lets Puppeteer control the remote browser:

import puppeteer from "puppeteer-core";

const token = process.env.BROWSERLESS_TOKEN!;
const proxyUrl = encodeURIComponent(process.env.PROXY_URL!);
const browserWSEndpoint =
  `wss://production-sfo.browserless.io?token=${encodeURIComponent(token)}` +
  `&externalProxyServer=${proxyUrl}`;

const browser = await puppeteer.connect({ browserWSEndpoint });
try {
  const page = await browser.newPage();
  await page.goto(process.env.ROUTE_CHECK_URL ?? "https://example.com/", {
    waitUntil: "domcontentloaded",
  });
  const marker = process.env.EXPECTED_MARKER ?? "Example Domain";
  const body = await page.$eval("body", (element) => element.innerText);
  const validOutput = body.includes(marker);

  console.log(JSON.stringify({
    finalUrl: page.url(),
    validOutput,
  }));
  if (!validOutput) throw new Error("route-check output failed validation");
} finally {
  await browser.close();
}

Browserless scopes proxySticky=true to its built-in proxies. For an externalProxyServer route, configure affinity through the external supplier’s supported sticky endpoint or session credentials, then verify that the exit remains stable for the task. The Browserless flag does not establish affinity for an arbitrary external proxy. Do not call page.authenticate for the upstream credentials when they are already supplied through externalProxyServer; keep the URL out of logs and error payloads.

Separate failures before changing suppliers

Keep resource blocking and request interception off for the route check, or use exactly the same rules for the baseline and proxy runs. A blocked script or XHR can remove a required field and make a valid route appear to have failed. Treat the provider’s error response and the target’s response as separate observations.

Compare the route with a real workload

Measure one fixed slice through both the direct and external paths. Record valid tasks, response bytes, browser minutes, retries, blocked responses and supplier cost. Browserless documents six proxy units per MB for its residential proxy and two units per MB for its datacenter proxy in the built-in example; externalProxyServer does not use those built-in units. Confirm the current commercial terms before budgeting.

Do not use an external proxy to bypass a destination’s access rules. Check the target’s terms, robots guidance where relevant, personal-data obligations and rate limits. A route is an implementation detail; permission and output quality are separate acceptance criteria.

For Playwright connection details, see the Playwright proxy guide. If the upstream reports a 407, use the proxy authentication guide. The linked Browserless issue is a historical report about an older /function authentication problem, so treat it as troubleshooting context rather than a current product guarantee.