Browserbase Custom Proxies: Settings and Tests

// Merge this into your SDK session-creation options.
// Configuration only: no session is created here.
const sessionOptions = {
  proxies: [{
    type: 'external',
    server: process.env.PROXY_SERVER,
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD,
  }],
};
// Keep the Browserbase API key in the SDK client's configuration.
// Do not log sessionOptions: it contains proxy credentials.

Browserbase lets you specify an external HTTP or HTTPS proxy when creating a browser session. This lets you evaluate browser hosting and proxy routing separately. Check both the plan requirement and whether Browserbase can reach your chosen proxy before building a workflow around it.

Configure the session, then test the page

The Browserbase proxy reference places external proxy settings in the session's proxies array. An external entry identifies its type, server and authentication details. Keep those fields separate in your application's configuration so a browser API token cannot be mistaken for a proxy password.

The same reference says custom proxies are available on the Developer plan and above. Browserbase validates the proxy connection during session creation and can reject an unreachable proxy. It explicitly cautions that not every provider is supported. A provider's HTTP endpoint therefore needs an actual session test before you describe it as a supported integration.

A small evaluation with clear pass conditions

1. Confirm that the proxy responds from a server environment before involving a hosted browser. This isolates basic credentials and routing problems.
2. Create one Browserbase session with the external proxy fields. Record a sanitized error if session creation fails.
3. Open a controlled diagnostic page inside that session. Check the address observed by the page; a check made by your local application measures a different connection.
4. Visit the target page you are permitted to use. Define success in advance, such as a particular heading or completed read-only action.
5. Repeat at low concurrency. Record failures and response times as well as successful requests.

Our gateway documentation explains where to obtain Proxies.sx connection details. Select a currently available route; the existence of a country selector in an application is not evidence of usable inventory in that country.

Keep routing and browser state separate

A browser profile can retain cookies while the network address changes. A proxy can also retain an address while you create a fresh browser profile. When investigating a login problem, record which of those two things changed. Otherwise, a test can attribute a cookie issue to the proxy or a routing issue to the browser.

For a regional check, compare the page's displayed location with the observed address and your requested route. Treat disagreement as a result to investigate. Do not silently count a response from a different region as a successful localized test.

What the official example contributes

Browserbase publishes a proxy automation template that covers built-in, regional and custom proxy configurations. Use that maintained starting point when evaluating its APIs. Adapt a small example first and record the SDK version with your test results.

Which protocol should I start with?

Use the HTTP or HTTPS proxy types documented by Browserbase. Do not assume that a provider's SOCKS5 endpoint is interchangeable in the same field.

Continue with the target-specific testing guide and proxy tester before committing a production workload.