Browserless External Proxies: Setup and Limits

// Configuration only: this does not make a paid request.
const upstream = new URL(process.env.PROXY_SERVER);
if (!['http:', 'https:'].includes(upstream.protocol)) {
  throw new Error('Use an HTTP or HTTPS proxy endpoint');
}
upstream.username = encodeURIComponent(process.env.PROXY_USERNAME);
upstream.password = encodeURIComponent(process.env.PROXY_PASSWORD);

const endpoint = new URL(
  'https://production-sfo.browserless.io/content'
);
endpoint.searchParams.set('token', process.env.BROWSERLESS_TOKEN);
endpoint.searchParams.set('externalProxyServer', upstream.href);
// Send your /content request to endpoint after reviewing its body.
// Never log endpoint: it contains both sets of credentials.

Browserless can run a browser while a separate proxy provider handles its outbound connection. That arrangement is useful when you already have proxy credentials or need to test a particular network. The first decision is whether to use Browserless's built-in proxy service or bring your own provider.

Where the external proxy fits

Your application connects to Browserless. Browserless then routes the browser's requests through the configured proxy. Keep the browser-service token separate from the proxy username and password: they authenticate different connections.

The Browserless proxy guide documents externalProxyServer, which accepts an HTTP or HTTPS proxy URL with optional credentials. For a first test, use the documented query parameter with one browser connection.

Check the account and request options

According to the REST proxy documentation, external proxies on the hosted service require a paid plan. Combining an external proxy with the built-in residential or datacenter proxy option produces an error. The same documentation separates built-in proxy units from external proxy usage.

Budget for the browser service and your external provider separately. Using your own proxy does not make browser execution free, and a successful browser connection does not establish that a target page returned the data you need.

Prepare a configuration you can inspect

1. Take a working HTTP proxy address and its credentials from your provider. For Proxies.sx, start with the Pool Gateway guide.
2. Build the external proxy URL in your application, then encode it as a query parameter. Avoid manually joining a password containing @ or : into an unescaped URL.
3. Keep the Browserless token in a server-side secret. Redact connection URLs in logs because query strings can contain both service and proxy credentials.
4. Run one request to an endpoint you control that returns the observed client address. Compare the result with a direct connection before testing your real workflow.

Measure the result that matters

A useful test record includes the request time, target hostname, expected response, actual status and bytes transferred. Record whether the page reached its application-level success condition. A rendered login screen can be a technically successful HTTP response and still be the wrong result for your task.

Test an anonymous page first, then an authorized account workflow if needed. Keep cookies and routing consistent during that second test. Check the provider's session rules before assuming that a browser session keeps one public address throughout its lifetime.

Common configuration questions

Can I use an authenticated SOCKS5 endpoint?

The external-proxy URL parameter documents HTTP(S). Use the documented HTTP route when your provider supplies credentials.

Does a working connection establish compatibility for every website?

No. Test the particular site and authorized action you need. Network routing, page rendering and application access are separate checks.

Before increasing concurrency, use the proxy testing worksheet. For application-side configuration, continue to our developer guides.