User Agent Masking

The User-Agent header identifies your browser's engine, operating system, and version to websites. Sites use it to adjust rendering, load web fonts, and run basic bot detection checks. In headless automation, the default user agent often signals that you're running a bot.

Indirect vs. direct user agent changes

Directly overriding the user agent string in code is increasingly unreliable. Sites cross-check it against other signals: TLS fingerprint, canvas fingerprint, WebGL renderer, and JavaScript APIs. A UA string claiming to be Chrome on Windows while exposing a Linux canvas fingerprint is a common detection pattern.

A more reliable approach is to choose the right browser binary. Each binary ships with a user agent that matches its actual capabilities, so there's no mismatch for fingerprinting tools to catch:

Binary	User Agent style	Notes
Chromium	Chrome/...	Default; open-source, no proprietary codecs
Chrome	Chrome/...	Proprietary codecs, closer to real-browser fingerprint
Firefox	Firefox/...	Gecko engine; Playwright only
WebKit	AppleWebKit/...	Safari engine; Playwright only

For the full browser support matrix and when to use each binary, see Supported Browsers.

Disable headless mode

Adding &headless=false to your connection URL also changes the user agent. By default, Browserless runs in headless mode, which exposes HeadlessChrome in the UA string. Running with headless=false removes that signal.

Default (headless):

Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/120.0.0.0 Safari/537.36

With headless=false:

Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36

Connect with headless disabled:

wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE&headless=false

For fingerprint-level bot detection bypass, use Stealth routes or BrowserQL.

Set the user agent in code

Use this when you need a specific UA string, for example to test mobile rendering or match a target site's expected browser. Keep in mind that an overridden UA can still be detected through fingerprinting if other browser signals don't match.

Puppeteer

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE`,
});
const page = await browser.newPage();
await page.setUserAgent(
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
);

Playwright

Javascript

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(
  `wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE`
);

const context = browser.contexts()[0] || (await browser.newContext());
const page = await context.newPage();

await context.setDefaultUserAgent(
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
);

Python

import asyncio
from playwright.async_api import async_playwright

async def main():
    async with async_playwright() as p:
        browser = await p.chromium.connect_over_cdp(
            "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
        )

        context = browser.contexts[0] if browser.contexts else await browser.new_context()
        page = await context.new_page()

        await context.set_default_user_agent(
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
        )

asyncio.run(main())

Java

import com.microsoft.playwright.*;

public class PlaywrightExample {
    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().connectOverCDP(
                "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
            );

            BrowserContext context = browser.contexts().isEmpty()
                ? browser.newContext()
                : browser.contexts().get(0);

            context.setDefaultUserAgent(
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
            );
        }
    }
}

C#

using System;
using System.Threading.Tasks;
using Microsoft.Playwright;

class Program
{
    static async Task Main(string[] args)
    {
        var playwright = await Playwright.CreateAsync();
        var browser = await playwright.Chromium.ConnectOverCDPAsync(
            "wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE"
        );

        var context = browser.Contexts.Count > 0
            ? browser.Contexts[0]
            : await browser.NewContextAsync();

        await context.SetDefaultUserAgentAsync(
            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.125 Safari/537.36"
        );
    }
}

Common user agent strings

Chrome Desktop:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36

Safari Desktop:

Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_1) AppleWebKit/605.1.15

Mobile Chrome:

Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15

Next Steps

Stealth Routes

Use stealth browser routes for fingerprint-level bot detection bypass

CAPTCHA Solutions

Automatically solve CAPTCHAs and other challenge-response systems

Supported Browsers

Compare browser binaries and choose the right one for your use case