Launch Options

Launch options configure browser behavior across all automation libraries (Puppeteer, Playwright, etc.) when connecting to Browserless. Instead of using launch arguments in your local puppeteer.launch() or playwright.launch() methods, you specify them in the connection string when calling the connect methods.

// 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`
});

Configuration Methods

Browserless supports two universal approaches for configuring launch options:

Individual Query Parameters: For simple settings, append options directly to your connection string (e.g., &headless=false&stealth=true)

JSON Launch Parameter: For complex configurations, use the launch parameter with a JSON object containing both Chrome flags and Browserless-specific options. This structured approach is especially useful because certain characters must be escaped when being sent as query parameters. See the BaaS API Reference for complete parameter specifications.

Both methods work universally across all supported automation libraries and services.

Quick Examples

Here are working examples for major automation libraries demonstrating the connection syntax differences while using identical launch options:

Puppeteer

import puppeteer from "puppeteer-core";

const launchOptions = {
  headless: false,
  args: ['--window-size=1920,1080']
};

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()}`,
});

Playwright CDP

import playwright from "playwright";

const launchOptions = {
  headless: false,
  args: ['--window-size=1920,1080']
};

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

const browser = await playwright.chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?${queryParams.toString()}`
);

Playwright Connect

import playwright from "playwright";

const launchOptions = {
  headless: false,
  args: ['--window-size=1920,1080']
};

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

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

Individual Options Reference

For detailed information about individual Chrome flags and browser options, see the BaaS API Reference.

Advanced Configurations

You can find proxy related examples here - https://docs.browserless.io/baas/features/proxies and some of the other popular params include below (for full list look in the reference docs).

Use these as query parameters or within the launch JSON object, depending on the option. Library‑specific shapes may vary; see the Open‑API schema docs.

Option	What it does	Notes / Links
Session Timer	Sets max browser session duration (ms). Session auto‑closes after this time.	Separate from per‑operation timeouts (e.g., selector waits, navigation, reconnection). Limits based on your subscription plan.
Headless / Headful	Run in headless mode, or enable a virtual GUI (helpful for some bot‑detection scenarios).	Headful attaches a virtual display (xvfb) in our cloud.
Chrome Launch Flags	Pass Chrome command‑line switches and Browserless‑specific options.	Library options vary; see Open‑API link above.
Record	Enable session recording for debugging/monitoring.	See Screencast API.
Block Ads	Enable uBlock Origin to block ads/trackers and speed up scripts.	Uses an extension; may increase bot‑detection in some cases.

---

Puppeteer‑Specific Customizations

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.

These help tailor puppeteer.connect behavior and override Puppeteer defaults.

Slow Mo

Adds delays between actions to slow down automation. Useful for debugging or throttling. Value in milliseconds.

• How: launch: slowMo: <ms>

Ignore Default Args

Puppeteer sets a number of default Chrome flags. You can instruct Browserless to ignore them.

• How: launch: ignoreDefaultArgs: true | ["--some-arg", "--another-arg"]
• Caution: Disabling defaults can make Chromium unstable or prevent launch.

Ignore HTTPS Errors

Skip HTTPS certificate errors (e.g., self‑signed certs) during navigation.

• How: launch: ignoreHTTPSErrors: true

---

Advanced Chrome Flags Example

Browserless supports all Chrome command‑line switches on Enterprise plans (see the full list here: https://peter.sh/experiments/chromium-command-line-switches/).

The following flags are available to 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

Here's a comprehensive example showing how to use advanced Chrome flags:

import puppeteer from "puppeteer-core";

// Define advanced launch options
const launchOptions = {
  timeout: 180000,
  headless: false,
  stealth: true,
  ignoreDefaultArgs: true,
  ignoreHTTPSErrors: true,
  slowMo: 10,
  args: [
    '--window-size=1920,1080',
    '--force-color-profile=srgb',
    '--disable-features=VizDisplayCompositor',
    '--disable-web-security',
    '--disable-setuid-sandbox',
    '--disable-site-isolation-trials'
  ]
};

// 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()}`,
});

---

Need More Details?

• API Reference — Complete parameter specifications and technical details
• Proxy Configuration — Built‑in residential proxies and third‑party proxy setup
• Anti‑Detection Features — Advanced stealth and bot‑detection bypass techniques
• Session Management — Persistent sessions and advanced session handling