Browser Configuration

BrowserCat offers full control over your browser instances using just a handful of configuration options. Whether you’re using Playwright, Puppeteer, or any other CDP client, you’ll have an easy time tweaking your browser to your needs.

You have two options for configuring your browser:

BrowserCat-Opts header: This API provides you with full control over your browser instance, supporting all configuration options.
Query parameters: While not as fully-featured as the header syntax, you can use query parameters to quickly set the most common configuration options.

Deep docs…

Jump to the full documentation for specific configuration options:

Query parameters

The query parameters are a subset of the BrowserCat-Opts header. You can use them to set the most common configuration options:

interface BrowserCatOptsParams {
  // Set the region for your browser instance
  region?: string

  // Manually select your browser. Typically only necessary when working with userland `chrome`
  browser?: 'chrome' | 'chromium' | 'firefox' | 'webkit'

  // Configures headed/headless mode.
  // Playwright defaults to "old"
  // Puppeteer (and others) default to "new"
  headless?: 'new' | 'old' | boolean
}

`BrowserCat-Opts` header

The BrowserCat-Opts header receives a JSON object with the following shape:

interface BrowserCatHeaders {
  // Authenticate your requests...
  'Api-Key': string;
  
  // JSON `BrowserCatOptsHeader` object
  'BrowserCat-Opts': string; 
}

interface BrowserCatOptsHeader {
  // Set the region for your browser instance
  region?: string

  // Manually select your browser. Typically only necessary when working with userland `chrome`
  browser?: 'chrome' | 'chromium' | 'firefox' | 'webkit'

  // Configures headed/headless mode.
  // Playwright defaults to "old"
  // Puppeteer (and others) default to "new"
  headless?: 'new' | 'old' | boolean

  // Set additional CLI args for browser launch
  enableArgs?: string[]

  // Disable default CLI args for browser launch. Use `true` to disable all defaults.
  disableArgs?: string[] | boolean

  // Set browser features flags
  // E.G. Chrome'- `about://flags` or Firefox's `about:config`
  userPrefs?: Record<string, string | number | boolean>

  // Set the proxy server for your browser instance
  proxy?: {
    server: string
    username?: string
    password?: string
    bypass?: string
  }
}

Examples

Playwright request

import * as pw from 'playwright';

const bcatUrl = new URL('wss://api.browsercat.com/connect');
bcatUrl.searchParams.set('region', 'cdg');
bcatUrl.searchParams.set('browser', 'chrome');
bcatUrl.searchParams.set('headless', 'new');

const browser = await pw.chromium.connect(bcatUrl.href, {
  channel: 'chrome',
  headers: {
    'api-key': '<YOUR_API_KEY>',
    'browsercat-opts': JSON.stringify({
      enableArgs: ['--no-sandbox'],
      disableArgs: true,
      proxy: {
        server: 'http://proxy.example.com:8080',
      },
    }),
  },
});
await browser.close();

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run():
    async with async_playwright() as pw:
        query_params = {
            'region': 'cdg',
            'browser': 'chrome',
            'headless': 'new'
        }
        bcatUrl = f'wss://api.browsercat.com/connect?{urlencode(query_params)}'

        browser = await pw.chromium.connect(bcatUrl, headers={
            'Api-Key': '<YOUR_API_KEY>'
            'browsercat-opts': json.dumps({
                'enableArgs': ['--no-sandbox'],
                'disableArgs': True,
                'proxy': {
                    'server': 'http://proxy.example
                }
            })
        })
        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('region', 'cdg');
bcatUrl.searchParams.set('browser', 'chrome');
bcatUrl.searchParams.set('headless', 'new');

const browser = await puppeteer.connect({
  channel: 'chrome',
  browserWSEndpoint: bcatUrl.href,
  headers: {
    'api-key': '<YOUR_API_KEY>',
    'browsercat-opts': JSON.stringify({
      enableArgs: ['--no-sandbox'],
      disableArgs: true,
      proxy: {
        server: 'http://proxy.example.com:8080',
      },
    }),
  },
});
await browser.close();

import asyncio
from pyppeteer import connect

async def run():
    query_params = {
        'region': 'cdg',
        'browser': 'chrome',
        'headless': 'new'
    }
    bcatUrl = f'wss://api.browsercat.com/connect?{urlencode(query_params)}'

    browser = await connect({
        'browserWSEndpoint': bcatUrl,
        'headers': {
            'api-key': '<YOUR_API_KEY>',
            'browsercat-opts': json.dumps({
                'enableArgs': ['--no-sandbox'],
                'disableArgs': True,
                'proxy': {
                    'server': 'http://proxy.example
                }
            })
        }
    })
    await browser.close()

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