Stealth Mode

​

Overview

Morally “good” automations play a vital role in modern web development with automated browsers performing legitimate tasks like testing, scraping, and content aggregation. While anti-bot systems often block all automation by default, you can be a good citizen of the web by using tools that respect site resources and terms of service.

Stealth Mode enables your automated browser sessions to mimic real user behavior across different sessions and IPs.

• Basic Stealth Mode handles CAPTCHA solving and browser fingerprint customization
• Advanced Stealth Mode uses Browserbase’s custom-built Chromium Browser to avoid detection all together.

This guide shows you how to use these features responsibly.

​

Basic Stealth Mode

A browser fingerprint is the unique set of characteristics that websites use to identify and track browsers. With Stealth Mode, you can control these identifiers to customize how your automated browsers appear to websites.

​

Fingerprint

Control the browser identity and system properties to simulate different environments:

• browsers: Specify supported browsers [“chrome”, “firefox”, “edge”, “safari”].
• devices: Set the device type [“desktop”, “mobile”].
• locales: Choose browser language settings [“en-US”, “en-GB”, etc.].
• operatingSystems: Simulate different OS environments [“android”, “ios”, “linux”, “macos”, “windows”].

​

Viewport

​

Supported Viewport Sizes

Browserbase supports a predefined set of standard viewport sizes to ensure compatibility across different devices and browsers. When creating a session, you must select from the following supported viewport dimensions:

Desktop Viewports

Mobile Viewports

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({apiKey: process.env["BROWSERBASE_API_KEY"]!});

async function createBasicStealthSession() {
  const session = await bb.sessions.create({
    projectId: process.env["BROWSERBASE_PROJECT_ID"]!,
    browserSettings: {
      fingerprint: {
        browsers: ["chrome", "firefox", "edge", "safari"],
        devices: ["desktop", "mobile"],
        locales: ["en-US", "en-GB"],
        operatingSystems: ["android", "ios", "linux", "macos", "windows"],
        screen: {
          maxWidth: 1920,
          maxHeight: 1080,
          minWidth: 1024,
          minHeight: 768,
        }
      },
      viewport: {
        width: 1920,
        height: 1080,
      },
      solveCaptchas: true,
    },
    proxies: true,
  });
  console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
  return session;
}

const session = createBasicStealthSession();

For a complete list of available options when creating a session, please refer to our API documentation on creating a session.

​

Advanced Stealth Mode

While Basic Stealth Mode automatically detects and solves most CAPTCHAs, Advanced Stealth Mode reduces the chances of being flagged as a bot by using a custom version of the Chrome browser, built and maintained by the Browserbase Stealth Team.

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({apiKey: process.env.BROWSERBASE_API_KEY!});

async function createAdvStealthSession() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      advancedStealth: true,
    },
    proxies: true,
  });
  return session;
}

const session = await createAdvStealthSession();
console.log(session);

Proxies are still very important for reliable browsing, and it’s recommended to enable them alongside Advanced Stealth Mode. Learn more about our proxy infrastructure and configuration options.

Please note, this feature is currently in beta; if you have any feedback, please reach out to support@browserbase.com.

​

CAPTCHA Solving

Many websites use CAPTCHAs to distinguish between automated and human interactions, which can interrupt automation workflows. Browserbase provides integrated CAPTCHA solving to handle these challenges automatically, allowing your sessions to continue without manual intervention. CAPTCHA solving is enabled by default for Basic Stealth Mode and Advanced Stealth Mode.

How CAPTCHA Solving Works

• When a CAPTCHA is detected, Browserbase attempts to solve it in the background.
• Solving can take up to 30 seconds, depending on the CAPTCHA type and complexity.
• It’s recommended to enable proxies when using CAPTCHA solving for higher success rates.
• For custom CAPTCHAs, you can provide custom selectors to guide the solution process.

If you’d like to disable captcha solving, you can set solveCaptchas to false in the browserSettings when creating a session.

​

CAPTCHA Solving Events

Browserbase will emit a console log when a CAPTCHA is detected and being solved. You can listen to these events to wait until solving is complete before continuing with your automation.

const recaptcha = await page.goto("https://www.google.com/recaptcha/api2/demo");

page.on("console", (msg) => {
  if (msg.text() == "browserbase-solving-started") {
    console.log("Captcha Solving In Progress");
  } else if (msg.text() == "browserbase-solving-finished") {
    console.log("Captcha Solving Completed");
  }
});

​

Custom CAPTCHA Solving

If you encounter a non-standard, or custom captcha provider, you need to specify the explicit selector for the captcha image and button itself.

For this custom captcha provider, you’ll need to specify two CSS selectors:

<img class="LBD_CaptchaImage" id="c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage" src="/BotDetectCaptcha.ashx?get=image&amp;c=c_turingtestpage_ctl00_maincontent_captcha1&amp;t=759cbf332a684ae3abe16213fe76438c" alt="CAPTCHA">

<input name="ctl00$MainContent$txtTuringText" type="text" value="Enter the characters shown above" maxlength="6" id="ctl00_MainContent_txtTuringText" class="swap_value field" initialvalue="Enter the characters shown above" title="Enter the characters shown above">  

browserSettings: {
  captchaImageSelector: "#c_turingtestpage_ctl00_maincontent_captcha1_CaptchaImage",
  captchaInputSelector: "#ctl00_MainContent_txtTuringText"
}

​

Disabling CAPTCHA Solving

CAPTCHA solving typically takes between 5 and 30 seconds.

If you’d like to disable captcha solving, you can set solveCaptchas to false in the browserSettings when creating a session.

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({apiKey: process.env.BROWSERBASE_API_KEY!});

async function createSessionWithoutCaptchaSolving() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      solveCaptchas: false,
    },
  });
  return session;
}

const session = await createSessionWithoutCaptchaSolving();
console.log(session);

​

Best Practices for Reliable Automation

Follow these best practices to ensure stable, efficient, and responsible automation with Browserbase.

​

Site Compliance & Ethical Automation

Before automating a website:

• Review the site’s terms of service to ensure compliance.
• Check robots.txt for crawling guidelines when applicable.
• Cache responses to reduce unnecessary requests and improve efficiency.

​

Request Rate Management

To maintain stability and avoid detection:

• Add delays between requests to mimic human behavior.
• Implement exponential backoff when encountering errors.
• Monitor request frequency and adjust based on site response times.

​

CAPTCHA Challenges

If you encounter CAPTCHAs:

• Check that proxies are enabled.
• Allow up to 30 seconds for CAPTCHA solving to complete.
• For custom CAPTCHAs, double-check that your selectors are correctly defined.

By following these best practices and troubleshooting steps, you can improve automation reliability, minimize detection risks, and optimize performance with Browserbase.

Need help? Contact support@browserbase.com