How to Handle Automatic CAPTCHA Solving in Browser Automation with Browserbase

Browserbase enables automatic CAPTCHA solving via the --solve-captchas flag on the bb sessions create command, which transparently handles reCAPTCHA v2/v3, hCAPTCHA, and Cloudflare Turnstile challenges through server-side AI-powered middleware without requiring additional libraries or API keys in your automation scripts.

Handling CAPTCHAs is a common hurdle in browser automation workflows. The browserbase/skills repository provides a built-in solution through the Browserbase CLI that automatically solves CAPTCHA challenges when creating managed browser sessions.

How Automatic CAPTCHA Solving Works

When you append the --solve-captchas flag to your session creation command, the CLI translates this into a JSON body field solveCaptchas: true that the Browserbase platform interprets to enable CAPTCHA-solving middleware. According to the implementation details in skills/browserbase-cli/SKILL.md and the flag table in skills/browserbase-cli/REFERENCE.md (lines 336-344), this middleware proxies page loads, detects challenges using AI-powered solvers, and forwards the solved page back to your session.

Because the solving happens server-side within the Browserbase infrastructure, you avoid embedding third-party libraries or exposing API keys in your automation scripts. The feature supports common challenge types including reCAPTCHA v2/v3, hCAPTCHA, and Cloudflare Turnstile.

Enabling CAPTCHA Solving in CLI Sessions

Basic Session Creation

To create a new browser session with automatic CAPTCHA solving enabled, add the --solve-captchas flag to your bb sessions create command:

bb sessions create --solve-captchas --region us-east-1

This provisions a session in the us-east-1 region where any encountered CAPTCHA will be solved automatically before the page content reaches your script.

Persistent Sessions with Context IDs

You can combine CAPTCHA solving with persistent contexts to maintain solved states across multiple sessions. Use the --context-id and --persist flags as documented in skills/browserbase-cli/SKILL.md:

bb sessions create \
  --solve-captchas \
  --context-id ctx_abc \
  --persist \
  --region us-west-2

This command re-uses the context ctx_abc and preserves any solved CAPTCHA states after the browser disconnects, allowing subsequent sessions to bypass previously solved challenges.

Disabling CAPTCHA Solving

To explicitly disable automatic solving for a specific session (overriding any default settings), use the --no-solve-captchas flag:

bb sessions create --no-solve-captchas --region eu-central-1

When this flag is present, the session behaves like a standard headless browser with no CAPTCHA assistance, even if challenges appear on the page.

Combining CAPTCHA Solving with Other Features

The --solve-captchas flag is additive and works seamlessly with other Browserbase CLI capabilities. As noted in the browserbase/skills documentation, you can combine it with proxy routing, stealth modes, and session recording:

bb sessions create \
  --solve-captchas \
  --proxies \
  --advanced-stealth \
  --record-session \
  --context-id myCtx \
  --persist

This creates a session with automatic CAPTCHA solving, proxy routing, advanced stealth protections, and full session recording enabled simultaneously.

Programmatic Integration

Since the Browserbase CLI returns structured output, you can invoke CAPTCHA-solving sessions from any programming language that executes shell commands.

Node.js Example

The following JavaScript spawns a Browserbase session with CAPTCHA solving enabled and captures the session ID from JSON output:

const { execSync } = require('child_process');

// Create a session with CAPTCHA solving enabled
const sessionId = execSync(
  'bb sessions create --solve-captchas --output json',
  { encoding: 'utf8' }
).trim();

console.log('Session created:', sessionId);

Shell Scripting

For bash-based automation workflows, capture the session ID and immediately launch a debugging session:

#!/bin/bash
SESSION_ID=$(bb sessions create --solve-captchas --output json)
echo "Started CAPTCHA-enabled session: $SESSION_ID"

Summary

• Enable solving by adding --solve-captchas to bb sessions create commands; the flag translates to solveCaptchas: true in the platform API.
• Persist state across sessions by combining the flag with --context-id and --persist.
• Disable solving explicitly with --no-solve-captchas when you need standard browser behavior.
• Cross-platform support works with any language via CLI invocation; no client-side libraries or API keys required.
• Reference documentation is located in skills/browserbase-cli/SKILL.md and skills/browserbase-cli/REFERENCE.md within the browserbase/skills repository.

Frequently Asked Questions

What types of CAPTCHAs does Browserbase automatically solve?

Browserbase handles reCAPTCHA v2/v3, hCAPTCHA, and Cloudflare Turnstile challenges. The server-side AI-powered middleware detects these specific challenge types during page load and solves them before returning the page content to your session.

Do I need to install additional libraries to use automatic CAPTCHA solving?

No additional libraries are required. The feature is built into the Browserbase platform and activated via the CLI flag. Because solving occurs server-side in the Browserbase infrastructure, you do not need to integrate third-party CAPTCHA-solving services or expose API keys in your automation code.

Can I use automatic CAPTCHA solving with existing browser contexts?

Yes. Combine --solve-captchas with --context-id and --persist flags to reuse existing contexts. This allows your automation to maintain solved CAPTCHA states across multiple sessions, reducing redundant solving operations for frequently accessed sites.

How do I verify that CAPTCHA solving is enabled for my session?

Check that you included the --solve-captchas flag in your bb sessions create command. As documented in skills/browserbase-cli/REFERENCE.md, omitting the flag defaults to disabled solving, while including it explicitly sets the internal solveCaptchas parameter to true for that specific session.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}