Browserless Docs

Browserless works almost identically to how most libraries and web-drivers work when ran locally. There’s no additional software you need to install on your production machines or complicated setup steps. As a matter of fact, the only thing you really need to when using the browserless service is merely change where your code references Chrome.

We’ve documented how to integrate with popular libraries in the left-hand pane, and have a quick start-guide for folks starting fresh.

How sessions work

Browserless runs Chrome in a cloud environment, and exposes all of the Chrome remote protocol to you. On top of exposing these commands, it also:

Typically, most libraries will issue an HTTP request to one of the /json endpoints exposed by Chrome’s dev protocol. When this request happens, browserless will create a fresh Target and return the resulting payload. This typically looks like:

Introspection Request

# curl https://chrome.browserless.io/json?token=YOUR-API-KEY
[
   {
      "description":"",
      "devtoolsFrontendUrl":"/devtools/inspector.html?ws=138.197.93.72:3000/devtools/page/da78a5e7-1db5-4d47-a2a5-07885088ad07",
      "id":"da78a5e7-1db5-4d47-a2a5-07885088ad07",
      "title":"about:blank",
      "type":"page",
      "url":"about:blank",
      "webSocketDebuggerUrl":"ws://138.197.93.72:3000/devtools/page/da78a5e7-1db5-4d47-a2a5-07885088ad07"
   }
]

The websocket endpoints are where commands from the protocol are emitted into, and Chrome will then emit responses back. Browserless does not modify or alter any of these messages. Once your session and underlying websocket are closed, browserless will automatically clear that Target and session data.

WebSocket Request

Libraries like puppeteer and chrome-remote-interface can hook into an existing Chrome instance by websocket. Browserless also supports this protocol as well, and you can typically replace how you start Chrome with a connect-like statement:

// Connecting to Chrome locally
const browser = await puppeteer.launch();

// Connecting to browserless
const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://chrome.browserless.io/?token=YOUR_API_TOKEN'
});

After that your code should remain exactly the same.

Timers

By default, browserless sets a cap of 30 seconds on each session, which it will then terminate. It’s a good idea to always cleanly exit or disconnect once your script is done as this triggers browserless to cleanup the session. It also results in browserless being more responsive as it can begin taking more work to be done.