# How to Handle Automatic CAPTCHA Solving in Browser Automation with Browserbase

> Learn to handle automatic CAPTCHA solving in browser automation with Browserbase. Our AI middleware solves reCAPTCHA, hCAPTCHA, and Turnstile challenges effortlessly.

- Repository: [browserbase/skills](https://github.com/browserbase/skills)
- Tags: how-to-guide
- Published: 2026-05-01

---

**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`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/SKILL.md) and the flag table in [`skills/browserbase-cli/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/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:

```bash
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`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/SKILL.md):

```bash
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:

```bash
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:

```bash
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:

```javascript
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:

```bash
#!/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`](https://github.com/browserbase/skills/blob/main/skills/browserbase-cli/SKILL.md) and [`skills/browserbase-cli/REFERENCE.md`](https://github.com/browserbase/skills/blob/main/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`](https://github.com/browserbase/skills/blob/main/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.