Skip to main content

CaptchaKraken

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

A live reCAPTCHA 4×4 tile grid challenge being solved end to end A live GeeTest slide jigsaw challenge being solved end to end

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

Vendor Puzzles
reCAPTCHA 3×3 and 4×4 image grids, including the dynamic re-deal
GeeTest v3 + v4 Slide, icon, nine, svg, gobang, iconcrush
NetEase Yidun Jigsaw, picture-click, icon-click
Tencent, Lemin, Prosopo Slide, cropped-image and grid flows
BotDetect, MTCaptcha, Yandex Distorted text — read and typed, not clicked
Cloudflare Turnstile Via the checkbox flow (free on the hosted API)

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.

Variable Meaning Default
VLLM_BASE_URL Inference endpoint ~/.captchakraken/credentials, else http://localhost:8000/v1
CAPTCHA_KRAKEN_API_KEY Bearer token (VLLM_API_KEY also accepted) ~/.captchakraken/credentials, else EMPTY
CAPTCHA_BASE_MODEL Base weights vLLM loads RedHatAI/Qwen3.5-9B-FP8-dynamic
CAPTCHA_LORA_ADAPTER Captcha adapter (HF id or path) CaptchaKraken/CaptchaKraken-Lora-v1.2
CAPTCHA_LORA_NAME Served adapter name the client requests captcha-v12
CAPTCHA_KRAKEN_AUTOSTART 0 disables local auto-start 1
CAPTCHA_KRAKEN_DETECTOR A local element-detector .onnx to run instead of downloading the released one the released weights, fetched once
CAPTCHA_KRAKEN_DETECTOR_MODEL Which released detector runs: lite (MobileNetV3, about 100 ms a board on one vCPU), standard (ResNet-18), or auto; overrides detector in captchakraken.config.json the config's detector, shipped as auto: lite on two usable CPUs or fewer (a container's CPU quota included), else one board is timed and standard runs when it fits in 200 ms
HF_TOKEN A Hugging Face token, sent only when downloading the detector weights from a private copy of their repo unset: the download sends no credential
CAPTCHA_HUMANIZATION How gestures are performed: mouse, mobile or none mouse

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.

Metadata

Release files for captchakraken 4.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for captchakraken 4.2.0
File Size Uploaded Provenance Actions
captchakraken-4.2.0.tar.gz 882.8 kB With provenance Details for captchakraken-4.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for captchakraken 4.2.0
File Interpreter ABI Platform Actions
captchakraken-4.2.0-py3-none-any.whl Python 3 none any Details for captchakraken-4.2.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / captchakraken-4.2.0.tar.gz

Download URL captchakraken-4.2.0.tar.gz
Size 882.8 kB
Tags Source
SHA-256 checksum
How to use checksums
187e133166abfc7c038b1fbbdb31171bc6e985a83a25430a4660c4c4bed47c2a
BLAKE2b-256 checksum
How to use checksums
f906b03949fe49efd21b20564097951d638547bdc892b6c1c9837309c8f7719e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / captchakraken-4.2.0-py3-none-any.whl

Download URL captchakraken-4.2.0-py3-none-any.whl
Size 226.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07bd8f5d4abcb9d6f94864dfdf46e54bc246f00d8b140a0f6f8810a5ac4b7c92
BLAKE2b-256 checksum
How to use checksums
4d023fb55f843e6a4588cb934a69a54c17cb363e67c238d1dd8f4ef35a12273e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for captchakraken 4.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for captchakraken-4.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page