Skip to main content
Version: v2

Reconnect to an existing Browser

note

Looking for full developer docs? See them here. This feature is only available on the Enterprise plans.

Reconnecting to an existing browser is useful if you want to avoid logging in multiple times, or if you leave a process pending and want to open a websocket connection again once you're ready to resume automation, amongst other use cases.

If you want to reconnect to a browser, all you have to do is fetch the browser's websocket endpoint which you can reconnect with later. You do so by using a CDP connection to the browser and triggering the Browserless.reconnect CDP command, which will keep that browser alive and allow you to reconnect to it within the specified timeout. This virtually replaces the keepalive flag that was previously used in V1.

Sample snippet

You can use the returned browserWSEndpoint to reconnect to a browser and continue working. The example below takes a screenshot after reconnecting:

import puppeteer from 'puppeteer-core';

const url = 'https://www.example.com';
const sleep = (ms) => new Promise((res) => setTimeout(res, ms));

const queryParams = new URLSearchParams({
token: 'YOUR_API_TOKEN_HERE',
timeout: 60000,
}).toString();

(async () => {
const browser = await puppeteer.connect({
browserWSEndpoint: `wss://production-sfo.browserless.io/chromium?${queryParams}`,
});
const page = await browser.newPage();
const cdp = await page.createCDPSession();
await page.goto(url);

// Allow this browser to run for 1 minute, then shut down if nothing connects to it.
// Defaults to the overall timeout set on the instance, which is 5 minutes if not specified.
const { error, browserWSEndpoint } = await cdp.send('Browserless.reconnect', {
timeout: 60000,
});

if (error) throw error;
console.log(`${browserWSEndpoint}?${queryParams}`);

await browser.close();
//Reconnect using the browserWSEndpoint that was returned from the CDP command.
const browserReconnect = await puppeteer.connect({
browserWSEndpoint: `${browserWSEndpoint}?${queryParams}`,
});
const [pageReconnect] = await browserReconnect.pages();
await pageReconnect.goto(url);
await sleep(2000);
await pageReconnect.screenshot({
path: 'reconnected.png',
fullPage: true,
});
await browserReconnect.close();

})().catch((e) => {
console.error(e);
process.exit(1);
});

Session Timeout

By default, your sessions are governed by a timeout. This is set via your account page for the hosted service. You can override this behavior.

  • If you are running BaaS in Docker, you can specify a TIMEOUT environment variable in the docker run command to override the default timeout of 30 seconds.

  • If you need to override the timeout on a per-job basis, 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`,
    });
    // ...
note

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