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 surface-level challenges like visual CAPTCHAs and generates random, realistic fingerprints and viewports for each session.
• Advanced Stealth Mode mimics human-like environmental signals using a custom-built Chromium browser to avoid bot detection altogether.

This guide shows you how to use these features responsibly.

​

Basic Stealth Mode

Basic Stealth Mode focuses on solving what you can see — like visual CAPTCHAs and browser fingerprint clues that are commonly used to detect bots.

To make automation easier and more effective out-of-the-box, Browserbase automatically generates random browser fingerprints and viewports for each session. This avoids the need for manual configuration.

​

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);

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);

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def create_stealth_session():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        proxies=True,
        browser_settings={
            "advanced_stealth": True,
        },
    )
    return session

session = create_stealth_session()
print(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");
  }
});

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");
  }
});

# Add this code where you want to check for CAPTCHA solving
def handle_console(msg):
    if msg.text == "browserbase-solving-started":
        print("Captcha Solving In Progress")
    elif msg.text == "browserbase-solving-finished":
        print("Captcha Solving Completed")

page.on("console", handle_console)

​

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);

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);

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def createSessionWithoutCaptchaSolving():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        browser_settings={
          "solveCaptchas": False,
        }
    )
    return session

session = createSessionWithoutCaptchaSolving()
print(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