Browserless Docs

Welcome to the documentation site for browserless! Here you’ll find resources on getting started with the service, and a little about how it works.

Browserless was created to solve a problem that many have faced: how do I build an application that relies on a web browser? At first it might seem easy to use something like Amazon Web Services or other hosted environments, but how do keep the footprint low and ensure service reliability? This is main motivation for browserless: a solution to hosting a headless browser.

Currently there are two ways to use this service: a monthly subscription where you get access to a headless instance with varying degrees of concurrent requests, or via a docker image where you can run and execute wherever you like.

See an issue with the docs or need help? Send us an email!

Hosted

If you choose to use a hosted package you’ll need an API key to connect to the service. This is a UUID string that looks like bef17c08-ae73-42a1-95aa-351854e3df6c. This key is emailed to you once you sign-up, and is viewable from your account page. Once you have this key you should only need to change one line of code in your application in order to have browserless run your headless script. See the appropriate documentation for the library that you use.

Hosted plans are great for projects where you just need a headless-browser ready to go. After signing up your account should be ready in less than 5 minutes. Browserless also ensure that the Chrome remains available, so if a page or script causes it to crash we’ll immediately restart it so that your application doesn’t come to a halt. Below is an example of using the puppeteer library and browserless:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://chrome.browserless.io?token=bef17c08-ae73-42a1-95aa-351854e3df6c'
  });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'example.png'});

  await browser.close();
})();

Self-hosted

If you wish to use the self-hosted Corporate plan, you’ll immediately get access to the docker hub repository where the browserless images are maintained. From there you can pull any tag you want and launch as many instances as you need. We’ve documented the parameters you can launch with in the sidebar, so be sure to read on how to configure the image to suite your needs.

Below is a quick script for pulling the image and running it.

# Pull the latest image from browserless
$ docker pull browserless/chrome

# Run it on port 3000
$ docker run --cap-add SYS_ADMIN -p 3000:3000 --restart always -d browserless/chrome

This tells docker to run the image in a container on port 3000, and to restart if there’s any issues. By default this is how hosted plans are ran inside of browserless.

Using the debugger

Both hosted and self-hosted images come bundled with the browserless debugger. This debugger allows you to execute arbitrary puppeteer scripts right from your web-browser and view the results in real-time. You can even use things like debugger and console.log messages to interactively see what’s happening in the webpage Chrome is at.

Below is an example of a script running against a browserless account

Browserless Debugger

Have Questions?

If the documentation here doesn’t answer questions you have, or you would like support for another library, please email us at help@browserless.io. We’d be more than happy to answer any questions you have or point you in the right direction!