captchakraken

A captcha solver for browser automation.
The Python engine and CLI behind CaptchaKraken.

CPU element detection plus a fine-tuned Qwen3.5-9B vision model. Give it a screenshot of a captcha and it returns the plan to solve it — which tiles to select, where to click, what to drag, how far to slide, or what text to type. Ships the captchakraken command.

Run the model on your own hardware, or point it at the hosted API and run nothing at all.

For demo videos, accuracy numbers, the browser driver, and the full self-hosting guide, see the main repo CaptchaKraken.

Watch it work

reCAPTCHA 4×4 tile grid 9/10 in 8.7s · GeeTest slide jigsaw 10/10 in 7.6s — median of the solved attempts, measured 2026-08-19 on captcha-v12 against each vendor's own public demo page. Counts rather than percentages because ten attempts is not a percentage. Idle time is cut from the clips, so they run shorter than the solves they show.

More puzzle types, as video and with the full method, at captchakraken.com and in the main repo.

What it solves

44 puzzle types, driven end to end in CI against generated fixtures on both the TypeScript and Python ports. Animated challenges are recorded, sliced into keyframes and answered with the frame the action belongs to.

Install

pip install captchakraken            # client: CPU element detection + vLLM HTTP planner
pip install "captchakraken[serve]"   # + the serving stack (vLLM/torch) to self-host

The base install is lightweight — everything you need to solve captchas against a vLLM server (local or remote). The [serve] extra pulls the heavy stack only if you want to run the model yourself. To skip all of that, pipx run captchakraken fetch asks which model and GPU you want, then installs, downloads and starts it, and captchakraken demo tries it.

No GPU? Use the hosted API

Point the client at https://api.captchakraken.com/v1 and run no model at all. Sign in at captchakraken.com/signin for a ck_live_… key, or let the MCP server write one for you:

claude mcp add captchakraken -- npx -y captchakraken-mcp
# then call sign_in, then create_api_key

create_api_key writes the key and the endpoint to ~/.captchakraken/credentials, which the client reads on its own — no environment variables needed.

Hands-off server

The vLLM server is managed for you. On your first solve, if the configured endpoint is local and nothing is listening, a server is started automatically and reused. Point VLLM_BASE_URL at a server you already run to skip local management entirely.

captchakraken server start | stop | status | run

Usage

# Solve an image/video: classify → find_grid → plan. Prints the click actions.
captchakraken path/to/captcha.png
captchakraken path/to/captcha.png --puzzle-source recaptcha

from captchakraken import CaptchaSolver

solver = CaptchaSolver()          # connects to / auto-starts a local vLLM
actions = solver.solve("captcha.png")

Element-detector tool subcommands (CPU only, no planner model): find-grid, find-checkbox, detect-selected, grid-cell-states, and a persistent serve worker the browser driver polls.

Configuration (model-agnostic)

Everything model-specific lives in captchakraken.config and is env-overridable — the solver never hard-codes a model.

How it moves is a choice of input device, not a realism dial. mobile dispatches real touch events with finger kinematics and never touches page.mouse; none goes straight to the DOM effect. Set it in code (which wins over the env var, because the right mode is a property of the page you are driving), and pass your own object to override ours entirely:

from captchakraken import PageSolver
from captchakraken.page_solver import PageSolverConfig

PageSolver(config=PageSolverConfig(humanization="mobile"))
PageSolver(config=PageSolverConfig(humanization="none"))
PageSolver(config=PageSolverConfig(humanizer=my_own))

# A real handset over Appium / Selenium — W3C touch pointer actions.
PageSolver(config=PageSolverConfig(
    humanization="mobile",
    touch_driver=driver,
    touch_transform={"scale": 3.0, "origin": (0, 132)},   # CSS px -> screen px
))

License

LGPL-3.0-only — see LICENSE. Use, modify and redistribute it, including in commercial and hosted services. If you distribute a modified version, keep the licence and copyright notices and make your changes available under LGPLv3.