HCaptchaSolver

A distributed hCaptcha solving system consisting of a FastAPI backend and an Electron desktop worker app.

Architecture

Client (HTTP)
     │
     ▼
┌─────────────┐   WebSocket    ┌──────────────────┐
│   Backend   │◄──────────────►│  Desktop Worker  │
│  (FastAPI)  │                │   (Electron)     │
└─────────────┘                └──────────────────┘

• Backend — receives solve requests via REST, queues them, and dispatches tasks to connected desktop workers.
• Desktop — Electron app that connects to the backend over WebSocket, receives tasks, solves captchas using an embedded browser view, and returns the token.

Project Structure

HCaptchaSolver/
├── backend/          # Python FastAPI server
│   ├── main.py
│   ├── requirements.txt
│   ├── core/
│   │   ├── models.py          # Task and Worker dataclasses
│   │   └── worker_manager.py  # Task queue and worker dispatch
│   ├── routers/
│   │   └── tasks.py           # REST endpoints
│   └── ws/
│       └── worker.py          # WebSocket handler for workers
└── desktop/          # Electron + React + TypeScript worker app
    └── src/
        ├── main/              # Electron main process
        ├── renderer/          # React UI
        └── preload/           # Preload scripts

Backend

Setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

python main.py

Server starts on http://0.0.0.0:8000.

API

Submit a task

POST /api/task
Content-Type: application/json

{
  "sitekey": "<hcaptcha-sitekey>",
  "siteurl": "https://example.com",
  "proxy": "http://user:pass@host:port"
}

Supported proxy schemes: http, https, socks5, socks5h.

Returns the solved token (blocks until a worker completes it, timeout 120 s):

{ "token": "<captcha-token>" }

Worker status

GET /api/workers

{ "total": 2, "available": 1 }

WebSocket — Worker Protocol

Workers connect to ws://<host>:8000/ws/worker and exchange JSON messages:

Direction	Message
Worker → Server	{ "type": "register" }
Server → Worker	{ "type": "registered", "worker_id": "..." }
Server → Worker	{ "type": "task", "task_id": "...", "sitekey": "...", "siteurl": "...", "proxy": "..." }
Worker → Server	{ "type": "result", "task_id": "...", "token": "..." }
Worker → Server	{ "type": "error", "task_id": "...", "message": "..." }

Desktop

Setup

cd desktop
npm install

Development

npm run dev

Build

npm run build:linux   # Linux
npm run build:win     # Windows
npm run build:mac     # macOS