Skip to main content
Version: v2

Launch Options

info

Currently, Browserless V2 is available in production via two domains: production-sfo.browserless.io and production-lon.browserless.io

Browserless allows you to control how Chrome is launched through query-string parameters in your puppeteer.connect's browserWSEndpoint URL or in your REST API calls. We allow you to set a launch query parameter as a way to specify Chrome launch options using a JSON object. This provides a clean, structured approach to setting up your browser environment, and it allows features like stealth mode, setting headful mode, and custom Chrome arguments.

Launching with our Residential Proxy​

While you can always use your own proxy service, we highly recommend using our built-in and first-party residential proxies. It is as simple as including proxy=residential in your query string, and specify the desired country with proxyCountry set to any valid ISO 3166 country code:

import puppeteer from "puppeteer-core";

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

Blocking ads​

You can use our built-in ad-blocker for both puppeteer.connect() and REST API calls. You'll simply need to add a query-string parameter of blockAds=true to your URL when connecting:

import puppeteer from "puppeteer-core";

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

Or for REST API calls:

// /pdf API
{
  "url": "https://browserless.io/",
  "blockAds": true,
  "options": {
    "format": "a5",
    "omitBackground": false,
    "printBackground": true,
    "scale": 1.5
  }
}

Under the hood, Browserless uses UBlock Origin to block ads and filter content.

Dynamic Launch Arguments​

You can pass dynamic launch arguments to Chrome by sending a JSON object and including it in the launch query parameter. This object can contain any Chrome launch arguments supported by Puppeteer and Browserless' launch options.

Stealth Mode​

You can use stealth mode to reduce bot-detection from blocking your scripts.

import puppeteer from "puppeteer-core";

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

Or for REST API calls:

// /pdf API
{
  "url": "https://browserless.io/",
  "options": {
    "format": "a5",
    "omitBackground": false,
    "printBackground": true,
    "scale": 1.5
  },
  "launch": {
    "stealth": true
  }
}

If stealth mode flags aren't enough to avoid bot detection, then try out BrowserQL.

Headful mode​

You can set the browser's headless mode using the headless query parameter. Running the browser in headful mode will launch the browser using the OS' GUI, in contrast to headless mode. This can be helphul to avoid more sophisticated bot-detection methods that rely on screen or rendering pattern detection.

import puppeteer from "puppeteer-core";

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

Or for REST API calls:

// /pdf API
{
  "url": "https://browserless.io/",
  "options": {
    "format": "a5",
    "omitBackground": false,
    "printBackground": true,
    "scale": 1.5
  },
  "launch": {
    "headless": false
  }
}

Chrome launch arguments​

In adition to the launch options Browserless offers, you can also use some of the Chrome launch flags inside the args array of the launch object.

import puppeteer from "puppeteer-core";

const launchArgs = JSON.stringify({
  args: ["--window-size=1920,1080", "--lang=en-US"],
});
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&launch=${launchArgs}`,
});
// ...

Or for REST API calls:

// /pdf API
{
  "url": "https://browserless.io/",
  "options": {
    "format": "a5",
    "omitBackground": false,
    "printBackground": true,
    "scale": 1.5
  },
  "args": [
    "--window-size=1920,1080",
    "--lang=en-US"
  ]
}

Caching with user-data-dir​

warning

Setting a user-data-dir is only available for Dedicated and self-hosted accounts (not on usage-based or cloud unit-based)

You can launch Chrome and specify a "user-data-dir" on each request to cache and make future sessions faster:

import puppeteer from "puppeteer-core";

const launchArgs = JSON.stringify({
  args: ["--user-data-dir=~/browserless-cache-123"],
});
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&launch=${launchArgs}`,
});
// ...

This can be used in conjuction with all our API's and integrations.

Ignoring default flags​

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.

import puppeteer from "puppeteer-core";

const launchArgs = JSON.stringify({
  args: ["--hide-scrollbars", "--disable-default-apps"],
});
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&launch=${launchArgs}`,
});
// ...

Overriding Puppeteer's launch args​

Since puppeteer.connect differs greatly from puppeteer.launch, Browserless allows to override Puppeteer's default launch arguments. These are specified through query-string parameters, and can be applied like so:

Ignore HTTPS Errors​

// Via puppeteer.launch()
puppeteer.launch({
  ignoreHTTPSErrors: true,
});

// Via puppeteer.connect()
puppeteer.connect({
  browserWSEndpoint: "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE",
  ignoreHTTPSErrors: true,
});

Slow Mo​

// Via puppeteer.launch()
puppeteer.launch({
  slowMo: 1000,
});

// Via puppeteer.connect()
puppeteer.connect({
  browserWSEndpoint: "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE",
  slowMo: 1000,
});

Ignore default args​

// Via puppeteer.launch()
puppeteer.launch({
  ignoreDefaultArgs: true,
});

// Via puppeteer.connect()
puppeteer.connect({
  browserWSEndpoint:
    "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&ignoreDefaultArgs=true",
});

Overriding the session timer​

By default, your sessions are governed by a timeout. This is set via your account page for the hosted service, or by specifying TIMEOUT in the docker run command. You can, on a per-job basis, override this behavior.

For puppeteer.connect and REST API's, simply specify a timeout parameter in your connect calls query-parameters, with the value being the time in milliseconds for the session to execute:

import puppeteer from "puppeteer-core";

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

The same can be used in REST API calls as well:

https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN&timeout=60000

For other runtimes and selenium libraries be sure to consult your libraries documentation, or contact us

Time to Live (TTL)​

Use the ttl key in your launch parameter to keep the browser instance alive for a specified duration, which allows for reconnections during this period.

import puppeteer from "puppeteer-core";

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

Available Chrome Args​

While most flags are supported, only certain args are allowed for usage-based accounts and cloud unit-based, and are listed below:

  • --proxy-server,
  • --window-size,
  • --disable-web-security,
  • --enable-features,
  • --disable-web-security,
  • --disable-setuid-sandbox,
  • --lang,
  • --font-render-hinting,
  • --force-color-profile,
  • stealth,
  • ignoreDefaultArgs,
  • headless,
  • token,
  • blockAds,
  • ignoreHTTPSErrors,
  • slowMo,