Version: v2

Launch Options

Launch options configure how browsers start and behave in your sessions. You can pass them as individual query parameters or as a single JSON launch parameter in the connection URL.

If you've used Puppeteer or Playwright locally, these are the cloud equivalent of browser.launch() options.

Passing Launch Options

There are two ways to pass options to the browser: as individual query parameters in the URL, or as a JSON object via the launch parameter.

Query parameters are passed directly in the connection URL (e.g., &headless=false&stealth=true). Best for simple, standalone settings.
The launch object is a JSON string passed as a single launch query parameter, either URL-encoded or base64-encoded. Use it for browser-level options like headless and stealth, or array flags like args: [...] whose brackets, quotes, and commas require encoding.

Both methods can be used together. Browserless merges them, with individual query parameters taking precedence.

Query Parameters

These are passed directly in the connection URL. The example below passes a token, a US residential proxy, and a 1-minute timeout:

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&proxy=residential&proxyCountry=us&timeout=60000`,
});

For the full list of query parameters, see the BaaS API Reference.

Parameter	Description	Default
`token`	The authorization token for API access.	none
`timeout`	Maximum session duration in milliseconds. The session will automatically close after this time to prevent overuse. Defaults to 60000ms. Maximum value depends on your plan (see Session Limits).	60000
`proxy`	Routes browser traffic through a proxy. Only supports proxy=residential for Browserless's residential proxy pool. Omit to use the IP of the machine in the cloud running the container, meaning it's a fixed datacenter IP.	none
`proxyCountry`	Used with proxy=residential to specify the exit node's country. Accepts ISO 3166 country codes (e.g., us, gb, de). If omitted, a random location is chosen.	none
`proxyCity`	Used with proxy=residential to specify the exit node's city (e.g., chicago, london). Requires Scale plan (500k+ units).	none
`proxySticky`	Used with proxy=residential to maintain the same proxy IP across a session (when possible). Useful for sites that expect consistent IP usage.	`false`
`proxyLocaleMatch`	Used with proxy=residential to automatically configure browser locale settings to match the proxy location. Recommended when using proxyCountry to improve stealth by aligning browser language preferences with the geographic region.	`false`
`proxyPreset`	Website-specific proxy configuration. Use px_gov01 for government websites or px_ipv6 for Google domains (Maps, YouTube, etc.) to ensure optimal proxy vendor selection.	none
`externalProxyServer`	External proxy server URL for user-provided proxies. Format: http(s)://[username:password@]host:port. When set, routes requests through this proxy instead of built-in residential proxies. Credentials can be included directly in the URL.	none
`blockAds`	Enables the built-in ad blocker (powered by uBlock Origin). Helps speed up scripts and reduce noise by blocking ads and trackers. Especially useful for scraping to avoid popups and clutter. Note: may cause some sites to fail to load correctly.	`false`
`record`	Enables session recording functionality for debugging and monitoring purposes.	`false`
`replay`	Enables session recording for replay. When true, the session is recorded and can be replayed later.	`false`

The `launch` Object

Options in the launch object are passed as an encoded JSON string. This is the cloud equivalent of Puppeteer's launch({ options }) or Playwright's launch({ options }), passed as a query parameter to the connection URL. See the full list of options in the API reference.

Parameter	Description	Default
`args`	Array of Chrome command-line flags to pass at browser launch (e.g. ["--window-size=1280,720", "--lang=en-US"]). See the Chrome Flags section for available flags.	[]
`headless`	Runs the browser in headless mode. Set to false to enable headful mode (with a GUI). While the GUI isn't visible in cloud environments, headful mode may help bypass bot detection. Note: it uses more resources.	`true`
`stealth`	Enables stealth mode to reduce automation signals (similar to puppeteer-extra's stealth plugin). Set to true to enable stealth techniques.	`false`
`slowMo`	Adds delays between browser actions to slow down automation. Useful for debugging or bypassing rate limits. Value in milliseconds.	0
`ignoreDefaultArgs`	Controls which default Puppeteer/Playwright arguments to ignore when launching the browser. Can be a boolean or array of specific arguments to ignore.	`false`
`acceptInsecureCerts`	Accepts insecure certificates during navigation. Useful for testing sites with self-signed certificates or certificate issues.	`false`

Encoding the `launch` Value

The launch value must be encoded before being appended to the URL. You can use URL encoding or base64. Both work the same way. Base64 is simpler because it avoids manually escaping brackets, quotes, and commas.

URL encoding

Puppeteer
Playwright CDP
Playwright Connect
Python

import puppeteer from "puppeteer-core";

const launch = JSON.stringify({
  args: ["--window-size=1280,720"],
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&launch=${encodeURIComponent(launch)}`,
});

import playwright from "playwright";

const launch = JSON.stringify({
  args: ["--window-size=1280,720"],
});

const browser = await playwright.chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&launch=${encodeURIComponent(launch)}`
);

import playwright from "playwright";

const launch = JSON.stringify({
  args: ["--window-size=1280,720"],
});

const browser = await playwright.chromium.connect(
  `wss://production-sfo.browserless.io/chromium/playwright?token=YOUR_API_TOKEN_HERE&launch=${encodeURIComponent(launch)}`
);

import json
import urllib.parse
from playwright.sync_api import sync_playwright

launch = json.dumps({
    "args": ["--window-size=1280,720"],
})

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&launch={urllib.parse.quote(launch)}"
    )

Base64 encoding

JavaScript
Python

import puppeteer from "puppeteer-core";

const launch = btoa(JSON.stringify({
  args: ["--window-size=1280,720"],
}));

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&launch=${launch}`,
});

import json
import base64
from playwright.sync_api import sync_playwright

launch = base64.b64encode(json.dumps({
    "args": ["--window-size=1280,720"],
}).encode()).decode()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&launch={launch}"
    )

Chrome Flags

Chrome flags are passed via the args array inside the launch object. Encode the value before use (see Encoding the launch Value above).

Before encoding:

{"args":["--window-size=1920,1080","--lang=en-US"]}

Encoded:

?launch=%7B%22args%22%3A%5B%22--window-size%3D1920%2C1080%22%2C%22--lang%3Den-US%22%5D%7D

Enterprise plans support the full set of Chrome command-line switches. The following flags are available to all accounts:

--disable-features
--disable-setuid-sandbox
--disable-site-isolation-trials
--disable-web-security
--enable-features
--font-render-hinting
--force-color-profile
--lang
--proxy-bypass-list
--proxy-server
--window-size

Puppeteer-Specific Options

Some launch object options behave differently under puppeteer.connect. Here are additional notes for Puppeteer users.

Ignore Default Args

On stealth routes (/stealth, /chromium/stealth, /chrome/stealth), you can pass an array to ignoreDefaultArgs to remove specific stealth-applied flags like --disable-dev-shm-usage. See Customizing Stealth Flags for details.

Disabling default args can make Chromium unstable or prevent launch entirely.

// Remove all default args
const launch = JSON.stringify({ ignoreDefaultArgs: true });

// Or remove specific args
const launch = JSON.stringify({ ignoreDefaultArgs: ["--disable-dev-shm-usage"] });

Accept Insecure Certificates

warning

acceptInsecureCerts replaces the older ignoreHTTPSErrors parameter, which has been renamed and deprecated by the Puppeteer team. Both are accepted for backwards compatibility, but use acceptInsecureCerts in new code.

Next Steps

Proxies

Configure residential proxies and third-party proxy servers

Bot Detection

Use stealth mode and humanlike behavior to avoid detection

Session Management

Persist cookies, storage, and browser state across sessions

Passing Launch Options​

Query Parameters​

The launch Object​

Encoding the launch Value​

Chrome Flags​

Puppeteer-Specific Options​

Ignore Default Args​

Accept Insecure Certificates​

Next Steps​