Headless/Headed Modes

By default, BrowserCat launches browsers in headless mode, e.g. without rendering the browser window. This mode is fast and efficient, but it can be easily detected by anti-bot measures.

Thus, we give you the option to override the default value and launch browsers either in chromium’s “new” headless mode or in headed mode.

“New” headless mode is more sophisticated and less likely to be detected by anti-bot measures, but it’s only available in chromium-based browsers. Headed mode is slower, but nearly identical to a real browser instance. And it’s available in all browsers.

Headless/headed modes

There are four modes available:

• “old” headless mode ("old"): Standard headless mode. Fast, but easily detected by anti-bot measures.
• “new” headless mode ("new"): Much closer to a real browser. More difficult to detect, but slower. Only available in chromium-based browsers. Learn more.
• Headed mode (false): A regular browser window. Slow, but nearly identical to a real browser instance.
• Default mode (true/undefined): The default headless mode for the client library you’re using.

Client defaults:

• Playwright defaults to “old” headless mode. “new” headless mode works well, but is currently still in beta.
• Puppeteer defaults to “new” headless mode.
• Other CDP clients default to “new” headless mode.

When to tweak headless mode

We recommend sticking to the default headless mode unless you have a specific reason to change it.

If you’re facing issues, first try switching to “new” headless mode. With few exceptions, this mode is nearly identical to a real browser instance. However, it’s only available in chromium-based browsers.

If you’re still facing issues, or if you need to work with a non-chromium browser, you can switch to headed mode. This mode is slower, but it is literally a real browser instance. However, it’s slower and consumes more resources, so you can’t open as many browser tabs without risking crashing your browser instance.

Remember that headless mode isn’t a silver bullet. It will circumvent bot detection on many websites, but in other cases, it will serve merely as a starting point. You may need to tweak other settings to get the best results.

Configure headless mode

Specify headless mode either using query parameters or the browsercat-opts header. The following examples user query params. For info on the browsercat-opts header, see the config overview.

Playwright request

import * as pw from 'playwright';

const bcatUrl = new URL('wss://api.browsercat.com/connect');
bcatUrl.searchParams.set('headless', 'false'); // headed mode

const browser = await pw.chromium.connect(bcatUrl.href, {
  headers: {'Api-Key': '<YOUR_API_KEY>'},
});
await browser.close();

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run():
    async with async_playwright() as pw:
        query_params = {
            'headless': 'false', # headed mode
        }
        bcatUrl = f'wss://api.browsercat.com/connect?{urlencode(query_params)}'

        browser = await pw.chromium.connect(bcatUrl, headers={
            'Api-Key': '<YOUR_API_KEY>'
        })
        await browser.close()

asyncio.get_event_loop().run_until_complete(run())

Puppeteer request

import puppeteer from 'puppeteer-core';

const bcatUrl = new URL('wss://api.browsercat.com/connect');
bcatUrl.searchParams.set('headless', 'false'); // headed mode

const browser = await puppeteer.connect({
  channel: 'chrome',
  browserWSEndpoint: bcatUrl.href,
  headers: {
    'api-key': '<YOUR_API_KEY>',
  },
});
await browser.close();

import asyncio
from pyppeteer import connect

async def run():
    query_params = {
        'headless': 'false'); # headed mode
    }
    bcatUrl = f'wss://api.browsercat.com/connect?{urlencode(query_params)}'

    browser = await connect({
        'browserWSEndpoint': bcatUrl,
        'headers': {
            'api-key': '<YOUR_API_KEY>'
        }
    })
    await browser.close()

asyncio.get_event_loop().run_until_complete(run())