waguriagentic/captcha-solver

What it solves

This project provides a self-hosted HTTP sidecar service that automatically solves CAPTCHA challenges. It eliminates the cost of external solving providers by running challenges natively within a real browser engine, allowing users to harvest replayable tokens or cookies for various bot-detection systems.

How it works

The service is built on the cloakbrowser Python library (an anti-detect Chromium browser). It exposes a FastAPI server that dispatches requests to specialized solvers based on the CAPTCHA type. Each solve request launches a dedicated CloakBrowser instance to interact with the challenge and extract the necessary validation token.

To handle headless server environments, the service runs under a virtual display (Xvfb) to support "headed" browser modes, which are less likely to be detected as bots. It also includes a dynamic concurrency semaphore that limits simultaneous browser instances based on available system RAM and CPU to prevent OOM (Out of Memory) crashes.

Who it’s for

Developers and automation engineers who need to integrate CAPTCHA solving into their workflows without relying on third-party paid APIs, preferring a self-hosted infrastructure for cost and control.

Highlights

• Broad Support: Solves 11 different types of challenges, including Turnstile, reCAPTCHA (v2/v3/Enterprise), hCaptcha, Cloudflare, AWS WAF, BotGuard, DataDome, PerimeterX, Akamai, Aliyun, and Arkose.
• Advanced Solving Techniques: Uses ONNX image classification for Arkose visual puzzles, cv2 gap detection for Aliyun slide-puzzles, and CDP gestures for PerimeterX biomechanics.
• SSRF Guard: Includes a built-in security layer that rejects requests to private, loopback, or reserved IP addresses to prevent Server-Side Request Forgery.
• Resource Management: Dynamically calculates concurrency limits based on live system resources and cgroup memory limits.
• Integrated Admin Dashboard: Features an optional React-based console for monitoring KPIs, solve history, and system status.