Skip to main content
Version: v2

Launch Options

What are Launch Options?​

When using a library such as Puppeteer, you can use launch options to configure how the browser is started and behaves during automation. However, with Browserless, you don't use those launch arguments in the puppeteer.launch() method. Instead, you specify them in the connection string when calling the puppeteer.connect() method:

// Instead of this:
const browser = await puppeteer.launch({ headless: true });

// You would do this:
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&headless=true`
});

Using Launch Options​

For simple cases as above, you can append an option as an individual query parameter to your connection string for commonly used options, such as &headless=false&token=....

Using the launch parameter is best, since it accepts a JSON object containing both Chrome flags and most Browserless-specific options. This structured approach is especially useful because certain characters must be escaped when being sent as query parameters.

Using the launch Parameter​

The launch parameter allows you to specify both Chrome flags and most Browserless-specific options in a structured way.

Here's how to use it:

import puppeteer from "puppeteer-core";

// Define launch options
const launchOptions = {
  timeout: 180000,
  headless: false,
  stealth: true,
  ignoreDefaultArgs: true,
  ignoreHTTPSErrors: true,
  slowMo: 0,
  args: [
    '--window-size=1920,1080', 
    '--force-color-profile=srgb'
    ]
};

// Create query parameters
const queryParams = new URLSearchParams({
  token: 'YOUR_API_TOKEN_HERE',
  proxy: 'residential',
  proxyCountry: 'us',
  proxySticky: 'true',
  record: false,
  launch: JSON.stringify(launchOptions)
});

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

Available Chrome flags​

All chrome flags are supported on Enterprise plans. The following chrome flags are available for all accounts, and should be defined inside the args object of the launch parameter.

  • --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

Chrome flags must be set as args inside the launch option.

import puppeteer from "puppeteer-core";

// Define launch options
const launchOptions = {
  args: [
    '--window-size=1920,1080', 
    '--force-color-profile=srgb'
    ]
};

// Create query parameters
const queryParams = new URLSearchParams({
  token: 'YOUR_API_TOKEN_HERE',
  launch: JSON.stringify(launchOptions)
});

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

Browserless-Specific options​

The following options are Browserless-specific and should be used as query parameters or within the launch JSON object accordingly:

ParameterDescriptionDefault
launchLaunch options, which contains Browserless-specific options and Chrome flags inside the args array.{}
tokenThe authorization token for API access.none
timeoutMaximum session duration in milliseconds. The session will automatically close after this time to prevent overuse.60000
headlessRuns 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
stealthEnables stealth mode to reduce automation signals (similar to puppeteer-extra's stealth plugin). In BQL, stealth is always on by design and controlled via the humanlike option. In BaaS/REST, set to true to enable stealth techniques.false (for BaaS/REST)
proxyRoutes 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
proxyCountryUsed 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
proxyStickyUsed with proxy=residential to maintain the same proxy IP across a session (when possible). Useful for sites that expect consistent IP usage.false
recordEnables session recording functionality for debugging and monitoring purposes.false
blockAdsEnables 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.false
slowMoAdds delays between browser actions to slow down automation. Useful for debugging or bypassing rate limits. Value in milliseconds.0
ignoreDefaultArgsControls which default Puppeteer/Playwright arguments to ignore when launching the browser. Can be a boolean or array of specific arguments to ignore.false
ignoreHTTPSErrorsIgnores HTTPS certificate errors during navigation. Useful for testing sites with self-signed certificates or certificate issues.false

Options​

Authenticating with an api token​

The authorization token for API access. This is required for all Browserless API calls Only Enterprise plans can have more than one API key per account.

Sign up for a Browserless account to retrieve your API key from the account page, we have free plan available.

Overriding the session timer​

Maximum browser session duration in milliseconds. The session will automatically close after this time to prevent overuse. This timeout is for the general browser session, not to be confused with the timeout that can be defined for waiting for selectors, navigation timeouts or reconnection timeouts.

Browserless enforces global session timeouts based on your subscription plan:

PlanMax Session TimeConcurrent Browsers
Free60 seconds1
Prototyping15 minutes3
Starter30 minutes20
Scale60 minutes50
EnterpriseCustomCustom

Headless and Headful mode​

Runs the browser in headless mode. Set to false will enable headful mode (attaches a virtual GUI with xvsb). While the GUI isn't visible to you when using our cloud service, headful mode may help bypass bot detection that rely on screen or rendering pattern detection.

Chrome Launch Flags​

The launch parameter allows you to specify both Chrome flags and Browserless-specific options in a structured way. This is the most flexible approach for configuring your browser session.

Libraries have different options for launch, you can verify your specific browser's options in the Open-API schema docs.

Caching with user-data-dir Launch flag​

Using a User Data Directory is an Enterprise feature which allows you to launch Chrome and specify a "--user-data-dir" flag on each request to cache and make future sessions faster, it will store cookies, localStorage, cache and login sessions across multiple browser sessions.

You can accomplish the same approach on cloud plans by using the Sessions API.

warning

Setting a --user-data-dir flag is only available for Enterprise and self-hosted plans (not on cloud unit-based plans)

Stealth​

Enables stealth mode by using puppeteer-extra-plugin-stealth to reduce automation signals. We have greatly improved this feature, consider using the /stealth path instead of the &stealth option, which will do a much better job at this.

warning

Need stronger anti-bot detection? Consider using BrowserQL which provides advanced anti-detection capabilities and human-like browsing behavior. It can be later used with Puppeteer or Playwright after bypassing security checks.

Launching with Proxies​

Proxies are useful to bypass bot-detection and solve most captchas, read more about this on our Built-in Residential Proxies and Third Party Proxies docs.

Geolocating your Proxies​

This option must be used in conjunction with proxy=residential to specify the exit node's country.

It accepts ISO 3166 country codes (e.g., us, gb, de). You can find the full list of ISO 3166 country codes here.

Sticky Proxies​

This option must be used in conjunction with proxy=residential to maintain the same proxy IP across a session, since requests use a different IP per request on the same browser session by default.

If you need the IP address to persist from one session to another, this option will not accomplish that. You can use a Third Party Proxy instead with statis residential proxies or if your use-case doesn't require it to be residential, you can use our sessions API which will keep your session on the same datacenter IP that it was initially instantiated on.

Record​

Enables session recording functionality for debugging and monitoring purposes. You can find more about our Screencast API here.

Block Ads​

This will enable uBlock Origin, which is an open-source ad blocker and content-filtering extension for web browsers like Chrome, Firefox, Edge, and Safari. Although this helps speed up scripts and reduce noise by blocking ads and trackers, it will use an extension under the hood, which could increase bot-detection.

Overriding Puppeteer's launch args​

Since puppeteer.connect differs greatly from puppeteer.launch, Browserless allows a way to override Puppeteer's default launch arguments. They can be applied using Browserless-Specific options through the following options.

Slow Mo​

Adds delays between browser actions to slow down automation. Useful for debugging or bypassing rate limits. Value in milliseconds.

Ignore Default Args​

By default Puppeteer specifies a certain number of launch flags in order to provide the best experience. In order to turn these off you'll want to tell Browserless to ignore them.

danger

Be careful ignoring these args as it might cause chromium to become unstable or refuse to launch.

Controls which default Puppeteer/Playwright arguments to ignore when launching the browser. Can be a boolean or array of specific arguments to ignore.

Ignore HTTPS Errors​

Ignores HTTPS certificate errors during navigation. Useful for testing sites with self-signed certificates or certificate issues.