How it WorksPricingDocsPlaygroundPluginsStatusBlog
Join Waitlist
← Back to Blog
·5 min read·GateSolve Team

Solve CAPTCHAs in Stagehand with GateSolve (3 Integration Options)

Stagehand by Browserbase is the browser automation SDK built for LLMs. It gives your AI agent natural language control over a browser. But when Cloudflare Turnstile, reCAPTCHA, or hCaptcha appears, the agent stalls. Here's how to add automatic CAPTCHA solving with GateSolve.

The Problem

Stagehand recently added auto-pause functionality when it detects a CAPTCHA challenge. The agent pauses, waiting for the CAPTCHA to be solved before continuing. But Stagehand doesn't include a solver — that's up to you.

Without a solver, your agent hits a CAPTCHA and stops. With GateSolve, it detects the CAPTCHA type, submits it for solving, injects the token, and continues — automatically.

Quick Start

Terminal
# Install Stagehand + GateSolve plugin
npm install @browserbase/stagehand @gatesolve/puppeteer-plugin

# Get a free API key (100 solves, no credit card)
curl -X POST https://gatesolve.dev/api/waitlist \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Option 1: Manual Solve (Full Control)

Use detectBlock() to classify the page state, then solveOnPage() to solve any detected CAPTCHA. This gives you full control over when and how solving happens.

stagehand-solve.ts
import { Stagehand } from "@browserbase/stagehand";
import { solveOnPage, detectBlock } from "@gatesolve/puppeteer-plugin";

const stagehand = new Stagehand({
  env: "LOCAL",
  modelName: "gpt-4o",
});

await stagehand.init();
const page = stagehand.page;

await page.goto("https://example.com/login");

// Step 1: Detect what kind of block you hit
const block = await detectBlock(page);
console.log(block.classification); // "captcha", "js-challenge", "public-ok"

if (block.classification === "captcha") {
  // Step 2: Solve the CAPTCHA
  const result = await solveOnPage(page, {
    apiKey: "gs_your_key",
    debug: true,
  });

  if (result?.success) {
    console.log("Solved!", result.type, result.solveTimeMs + "ms");
    // Page is now unblocked — continue automation
  }
}

// Step 3: Continue with Stagehand actions
await stagehand.act({ action: "click the login button" });

Option 2: Auto-Solve (Zero Friction)

Wrap your Stagehand page with withGateSolve() and every navigation automatically checks for and solves CAPTCHAs. No manual detection needed.

stagehand-auto.ts
import { Stagehand } from "@browserbase/stagehand";
import { withGateSolve } from "@gatesolve/puppeteer-plugin";

const stagehand = new Stagehand({
  env: "LOCAL",
  modelName: "gpt-4o",
});

await stagehand.init();

// Wrap the page — CAPTCHAs are solved automatically on every navigation
const page = withGateSolve(stagehand.page, {
  apiKey: "gs_your_key",
});

// Now every page.goto() auto-solves any CAPTCHA it encounters
await page.goto("https://example.com/protected-page");
// If there's a Turnstile/reCAPTCHA/hCaptcha, it's solved automatically

Option 3: MCP Server (Agent-Native)

If your agent uses MCP for tool discovery, add GateSolve as an MCP server. The agent gets solve_captcha, detect_captcha, and check_solve_status tools automatically.

MCP config
// Alternative: Use GateSolve MCP server with Stagehand
// In your MCP client config:
{
  "mcpServers": {
    "gatesolve": {
      "command": "npx",
      "args": ["@gatesolve/mcp-server"],
      "env": { "GATESOLVE_API_KEY": "gs_your_key" }
    }
  }
}

// Your LLM agent can now call solve_captcha and detect_captcha
// tools automatically when Stagehand encounters a block.
// The MCP server handles submit + poll + token return.

What detectBlock() Returns

Before solving, classify the page to avoid wasting solves on non-CAPTCHA blocks:

  • public-ok — Page loaded normally. No block detected.
  • captcha — CAPTCHA widget found. Solvable with GateSolve.
  • js-challenge — Cloudflare JS interstitial. Wait 5-10s or use stealth browser.
  • auth-wall — Login form. Not a CAPTCHA problem.
  • error-page — 403/blocked. Likely IP-level block.

Supported CAPTCHA Types

TypePriceAvg. Time
Cloudflare Turnstile$0.027-15s
reCAPTCHA v2/v3$0.0310-20s
hCaptcha$0.0310-20s

Why Not CapSolver?

CapSolver works, but there are tradeoffs:

FeatureGateSolveCapSolver
Free tier100 solvesNone
MCP serverOfficialNo
Puppeteer pluginnpmnpm
detectBlock()Built-inNo
Credit card requiredNoYes

Get Started

  1. Get a free API key: POST https://gatesolve.dev/api/waitlist with your email
  2. Install: npm install @gatesolve/puppeteer-plugin
  3. Integrate: Use any of the three options above
  4. First 100 solves are free — no credit card, no commitment

Ready to unblock your Stagehand agent?

100 free CAPTCHA solves. No credit card. Works with Stagehand, Browserbase, and any Playwright-based framework.

Read the Docs →
← All posts