DEV Community

luisgustvo
luisgustvo

Posted on

How to Bypass Any CAPTCHA in HyperBrowser Using CapSolver (Comprehensive Setup Guide)

#ai #webdev #agents #programming

AI-driven browser agents are fundamentally transforming how developers engage with the internet. These agents are capable of navigating web pages, completing forms, and extracting data autonomously, from data scraping to workflow automation. However, the appearance of a CAPTCHA invariably halts their progress.

HyperBrowser provides cloud-based browser infrastructure specifically engineered for AI agents, offering native CAPTCHA bypassing capabilities for Turnstile and reCAPTCHA. Nevertheless, the internet features a broader spectrum of CAPTCHA types. Challenges such as AWS WAF, GeeTest, various enterprise reCAPTCHA versions, and other anti-bot mechanisms often remain unaddressed by native tools alone.

CapSolver bridges this gap. By directly uploading the CapSolver Chrome extension to HyperBrowser via its extension API, users gain extensive CAPTCHA coverage across all sessions, for every CAPTCHA type, and at any scale, without requiring modifications to their existing automation code.

Introduction to HyperBrowser

HyperBrowser is a cloud browser infrastructure platform specifically designed for AI agents. It delivers managed browser sessions with out-of-the-box native Chrome DevTools Protocol (CDP) access, proxy support, and advanced anti-detection features.

Key Features

  • Cloud Browser Sessions: Enables the on-demand creation of isolated browser instances, eliminating the need for local Chrome installations.
  • Native CDP Access: Facilitates direct connection of Playwright, Puppeteer, or Selenium to cloud sessions via WebSocket.
  • HyperAgent: An integrated AI browser automation agent for executing web tasks using natural language.
  • Anti-Detection Capabilities: Incorporates stealth profiles, residential proxies, and fingerprint randomization into every session.
  • Chrome Extension Support: Offers a robust extension upload API, allowing users to ZIP an extension, upload it, and attach it to any session.
  • Scalable Infrastructure: Supports running hundreds of concurrent sessions without the complexities of managing browser pools.

Why Developers Opt for HyperBrowser

HyperBrowser alleviates the operational overhead associated with browser automation. Instead of managing Chromium binaries, configuring headless modes, rotating proxies, and implementing anti-fingerprinting measures, developers receive a streamlined API that provides a WebSocket URL. This allows for immediate automation by connecting existing Playwright or Puppeteer scripts.

Introduction to CapSolver

CapSolver is a leading service for bypassing CAPTCHAs, offering AI-powered solutions to overcome various CAPTCHA challenges. With support for numerous CAPTCHA types and rapid response times, CapSolver integrates seamlessly into automated workflows.

Supported CAPTCHA Categories

Prerequisites

Before initiating the integration setup, ensure the following components are available:

  1. A HyperBrowser account with an associated API key (sign up at hyperbrowser.ai)
  2. A CapSolver account with an API key and sufficient credits (sign up here)
  3. The CapSolver Chrome extension downloaded and properly configured.
  4. Node.js 18+ with @hyperbrowser/sdk and playwright-core installed. 
npm install @hyperbrowser/sdk playwright-core
Enter fullscreen mode Exit fullscreen mode

Step-by-Step Configuration

Step 1: Acquire Your CapSolver API Key

  1. Register or log in at capsolver.com.
  2. Navigate to your Dashboard.
  3. Copy your API key (it follows the format: CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX).
  4. Add credits to your account (utilize bonus code HYPERBROWSER for an additional 6% on your initial recharge).

Step 2: Download and Configure the CapSolver Extension

Download the CapSolver Chrome extension and set it up with your API key:

  1. Visit the CapSolver extension releases on GitHub.
  2. Download the most recent CapSolver.Browser.Extension-chrome-vX.X.X.zip file.
  3. Extract the extension contents: 
mkdir -p capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d capsolver-extension/
Enter fullscreen mode Exit fullscreen mode
  1. Open capsolver-extension/assets/config.js and insert your API key: 
export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // your key here
  useCapsolver: true,
  // ... rest of config
};
Enter fullscreen mode Exit fullscreen mode
  1. Verify the extension's directory structure: 
ls capsolver-extension/manifest.json
# This file should be present
Enter fullscreen mode Exit fullscreen mode

Step 3: Compress the Extension Directory into a ZIP File

HyperBrowser's extension upload API mandates a ZIP file. Package the configured extension:

cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..
Enter fullscreen mode Exit fullscreen mode

This action generates capsolver-extension.zip in your project's root directory, ready for upload.

Step 4: Upload the Extension to HyperBrowser

Utilize the HyperBrowser SDK to upload the extension ZIP file. This is a one-time operation; the returned extensionId can be reused across all subsequent sessions.

import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

// Upload the CapSolver extension (a single operation)
const ext = await client.extensions.create({
  filePath: "capsolver-extension.zip",
});

console.log("Extension ID:", ext.id);
// Retain this ID for reuse in every session
Enter fullscreen mode Exit fullscreen mode

Guidance: Store the ext.id in your environment variables or configuration. Re-uploading is only necessary if the extension version or API key is modified.

Step 5: Establish a Session with the Extension Enabled

Create a HyperBrowser session that incorporates the CapSolver extension:

const session = await client.sessions.create({
  extensionIds: [ext.id],
  useProxy: true, // Requires a paid plan — omit for the free tier
  bypassCaptchas: false, // Utilizing CapSolver instead of native bypassing
});

console.log("Session ID:", session.id);
console.log("WebSocket URL:", session.wsEndpoint);
Enter fullscreen mode Exit fullscreen mode

Note: Set bypassCaptchas: false when using CapSolver to prevent conflicts between the two bypassing mechanisms. For a fallback chain, refer to the "When to Use Native vs CapSolver" section below.

Step 6: Integrate Playwright with the Session

Connect Playwright to the HyperBrowser session via its WebSocket endpoint:

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(session.wsEndpoint);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

// Navigate to a CAPTCHA-protected web page
await page.goto("https://www.google.com/recaptcha/api2/demo");

// Allow time for the CapSolver extension to detect and bypass the CAPTCHA
await page.waitForTimeout(30000);

// Submit the form
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");

// Confirm successful bypass
const result = await page.textContent("body");
console.log("Result:", result);
// Expected outcome: the body text should contain "Verification Success"

await browser.close();
await client.sessions.stop(session.id);
Enter fullscreen mode Exit fullscreen mode

Step 7: Validate on a reCAPTCHA Demonstration Page

Below is a complete end-to-end script that uploads the extension, establishes a session, bypasses a CAPTCHA, and verifies the outcome:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { chromium } from "playwright-core";

const HYPERBROWSER_API_KEY = process.env.HYPERBROWSER_API_KEY!;
const CAPSOLVER_EXTENSION_ID = process.env.CAPSOLVER_EXTENSION_ID; // Optional: for reusing an existing ID

async function main() {
  const client = new Hyperbrowser({ apiKey: HYPERBROWSER_API_KEY });

  // Step 1: Upload extension (or utilize an existing ID)
  let extensionId = CAPSOLVER_EXTENSION_ID;

  if (!extensionId) {
    const ext = await client.extensions.create({
      filePath: "capsolver-extension.zip",
    });
    extensionId = ext.id;
    console.log("Uploaded extension:", extensionId);
  }

  // Step 2: Create a session with the CapSolver extension
  const session = await client.sessions.create({
    extensionIds: [extensionId],
    useProxy: true, // Requires a paid plan — omit for the free tier
    bypassCaptchas: false,
  });

  console.log("Session initiated:", session.id);

  // Step 3: Connect Playwright
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  try {
    // Step 4: Navigate to the reCAPTCHA demonstration page
    console.log("Navigating to reCAPTCHA demo...");
    await page.goto("https://www.google.com/recaptcha/api2/demo");

    // Step 5: Await CapSolver to bypass the CAPTCHA
    console.log("Awaiting CapSolver to bypass CAPTCHA...");
    await page.waitForTimeout(30000);

    // Step 6: Submit the form
    console.log("Submitting form...");
    await page.click("#recaptcha-demo-submit");
    await page.waitForLoadState("networkidle");

    // Step 7: Check the outcome
    const bodyText = await page.textContent("body");

    if (bodyText?.includes("Verification Success")) {
      console.log("CAPTCHA bypassed successfully!");
    } else {
      console.log("Verification result:", bodyText?.slice(0, 200));
    }
  } finally {
    await browser.close();
    await client.sessions.stop(session.id);
    console.log("Session terminated.");
  }
}

main().catch(console.error);
Enter fullscreen mode Exit fullscreen mode

To execute:

HYPERBROWSER_API_KEY=your_key npx tsx captcha-test.ts
Enter fullscreen mode Exit fullscreen mode

Operational Mechanics

Here is a detailed overview of the process, from extension upload to CAPTCHA bypassing:

  Initial Configuration
  ═══════════════════════════════════════════════════════

  capsolver-extension/           HyperBrowser Cloud
  ├── manifest.json    ──ZIP──►  POST /extensions
  ├── assets/con
Enter fullscreen mode Exit fullscreen mode

CAPTCHA Persistence (Form Submission Failure)

Symptom: The page loads, but the CAPTCHA remains unbypassed after a waiting period, leading to form submission failure.

Possible Explanations:

  1. Insufficient wait duration — Extend waitForTimeout to 45-60 seconds.
  2. Invalid API key — Access your CapSolver dashboard to confirm the validity of the key.
  3. Inadequate balance — Replenish your CapSolver account credits.
  4. Unsupported CAPTCHA type — Consult the CapSolver documentation for a list of supported types.

Session WebSocket Connection Issues

Symptom: chromium.connectOverCDP() generates a connection error.

Resolution: Verify that the session is still active. Sessions have a predefined timeout (which varies by plan). If the previous session has expired, create a new one:

try {
  const browser = await chromium.connectOverCDP(session.wsEndpoint);
} catch (err) {
  console.log("Session expired, initiating a new one...");
  const newSession = await client.sessions.create({
    extensionIds: [extensionId],
    useProxy: true, // Requires a paid plan — omit for the free tier
  });
  const browser = await chromium.connectOverCDP(newSession.wsEndpoint);
}
Enter fullscreen mode Exit fullscreen mode

Extension Discrepancy: Local vs. HyperBrowser Functionality

Symptom: The CapSolver extension operates correctly when loaded locally in Chrome but fails within HyperBrowser sessions.

Possible Explanations:

  1. config.js exclusion from ZIP — Double-check that the modified assets/config.js file is included in the ZIP archive.
  2. Network restrictions — The extension requires access to api.capsolver.com. Ensure that the HyperBrowser session's network configuration permits outbound HTTPS connections.
  3. Extension version incompatibility — For optimal compatibility, use the latest release of the CapSolver extension.

Recommended Practices

1. Upload the Extension Once, Reuse the Identifier

The extension upload is a singular event. Store the extensionId returned and reuse it across all subsequent sessions:

// Upload once
const ext = await client.extensions.create({ filePath: "capsolver-extension.zip" });
const CAPSOLVER_EXT_ID = ext.id;

// Reuse for each session
for (const url of targetUrls) {
  const session = await client.sessions.create({
    extensionIds: [CAPSOLVER_EXT_ID],
    useProxy: true, // Requires a paid plan — omit for the free tier
  });
  // ... automate
  await client.sessions.stop(session.id);
}
Enter fullscreen mode Exit fullscreen mode

2. Consistently Enable Proxies

CAPTCHAs are more prone to appear (and are more challenging to bypass) when requests originate from datacenter IP addresses. HyperBrowser's integrated proxies help mitigate this:

const session = await client.sessions.create({
  extensionIds: [extensionId],
  useProxy: true, // Requires a paid plan — omit for the free tier. Residential proxies reduce CAPTCHA frequency
});
Enter fullscreen mode Exit fullscreen mode

3. Employ Appropriate Waiting Periods

Different CAPTCHA types necessitate varying bypass durations:

CAPTCHA Type Typical Bypass Time Recommended Wait
reCAPTCHA v2 (checkbox) 5-15 seconds 30 seconds
reCAPTCHA v2 (invisible) 5-15 seconds 25 seconds
reCAPTCHA v3 3-10 seconds 20 seconds
Cloudflare Turnstile 3-10 seconds 20 seconds
AWS WAF 5-15 seconds 30 seconds
GeeTest v3/v4 5-20 seconds 30 seconds

Hint: When uncertain, a 30-second wait is generally advisable. It is preferable to wait slightly longer than to submit prematurely.

4. Monitor Your CapSolver Account Balance

Each CAPTCHA bypass consumes credits. Integrate balance checks into your automation to prevent interruptions:

import axios from "axios";

async function checkBalance(apiKey: string): Promise<number> {
  const response = await axios.post("https://api.capsolver.com/getBalance", {
    clientKey: apiKey,
  });
  return response.data.balance || 0;
}

const balance = await checkBalance(process.env.CAPSOLVER_API_KEY!);
if (balance < 1) {
  console.warn("Low CapSolver balance! Top up at capsolver.com");
}
Enter fullscreen mode Exit fullscreen mode

5. Terminate Sessions Appropriately

Always stop sessions once their purpose is fulfilled to avoid incurring unnecessary charges:

try {
  // ... your automation code
} finally {
  await browser.close();
  await client.sessions.stop(session.id);
}
Enter fullscreen mode Exit fullscreen mode

6. Re-ZIP After API Key Changes

If your CapSolver API key is rotated, you must update config.js, re-zip the extension, and re-upload it:

# Update the key in config.js, then:
cd capsolver-extension && zip -r ../capsolver-extension.zip . && cd ..
Enter fullscreen mode Exit fullscreen mode

Subsequently, upload the new ZIP file and update your stored extensionId.

Conclusion

The combined capabilities of HyperBrowser and CapSolver offer the most comprehensive CAPTCHA bypassing solution available for AI browser automation:

  1. HyperBrowser manages the underlying infrastructure, including cloud sessions, proxies, anti-detection features, and native Turnstile/reCAPTCHA bypassing.
  2. CapSolver extends this coverage to include AWS WAF, GeeTest, enterprise reCAPTCHA, and other CAPTCHA types not addressed by the native bypasser.

The integration process is straightforward: compress the CapSolver extension into a ZIP file, upload it once via the HyperBrowser SDK, and then attach it to any session. This approach eliminates the need for code-level CAPTCHA detection, token injection, or API polling, as the extension handles these aspects within the browser context.

Whether you are developing web scrapers, AI agents, or automated testing pipelines, this powerful combination ensures that CAPTCHAs no longer pose a barrier, regardless of their type.

Ready to begin? Sign up for CapSolver and use bonus code HYPERBROWSER for an extra 6% bonus on your initial recharge!

Frequently Asked Questions (FAQ)

What is HyperBrowser?

HyperBrowser is a cloud browser infrastructure platform designed for AI agents. It provides managed, isolated browser sessions with native CDP access, enabling connection of Playwright, Puppeteer, or Selenium to cloud-hosted Chromium instances. It includes built-in proxies, anti-detection features, and native CAPTCHA bypassing for Turnstile and reCAPTCHA.

How does the extension upload process work?

HyperBrowser features a dedicated extension API. You compress your Chrome extension directory into a ZIP file, upload it using client.extensions.create(), and receive an extensionId. This ID is then passed to client.sessions.create(), and the extension is automatically loaded into the cloud browser session.

Which CAPTCHA types does CapSolver support?

CapSolver supports reCAPTCHA v2 (both checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, Cloudflare 5-second Challenge, AWS WAF, GeeTest v3/v4, among others. The Chrome extension automatically detects and bypasses the CAPTCHA type.

What is the cost of CapSolver?

CapSolver offers competitive pricing structures based on CAPTCHA type and usage volume. Visit capsolver.com for current pricing details. Use the code HYPERBROWSER to receive a 6% bonus on your first recharge.

Is it necessary to re-upload the extension for every session?

No. The extension needs to be uploaded only once. The returned extensionId can be reused across all sessions. Re-uploading is only required if you modify the CapSolver API key within the extension or update the extension's version.

Can Puppeteer be used as an alternative to Playwright?

Yes. HyperBrowser is compatible with Playwright, Puppeteer, and Selenium. To use Puppeteer, replace the Playwright connectOverCDP call with Puppeteer's equivalent:

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: session.wsEndpoint,
});
Enter fullscreen mode Exit fullscreen mode

The CapSolver extension functions identically regardless of the automation framework used for connection.

Is HyperBrowser available for free?

HyperBrowser provides a free tier with a limited number of sessions. Paid plans unlock additional sessions, extended timeouts, and advanced features. For current pricing and plan details, visit hyperbrowser.ai.

Top comments (0)