How to Solve CAPTCHAs in a Windmill Script (Python)

A Windmill captcha solve is about as small as this integration gets. Windmill reads the imports at the top of your script, resolves them against PyPI and pins them in a lockfile, so the CapSkip SDK arrives with no install step and no requirements file. What is left is a main function that takes a sitekey and gives you back a token. The part worth thinking about is not the code, it is which machine the worker runs on, because that decides whether the solver stays on the loopback address or has to listen on your network.

What you need

• A Windmill instance, self-hosted or on their cloud, and a workspace you can deploy a script to.
• CapSkip running on a Windows machine. Local mode is fine if the worker runs on that same machine. If the workers live in containers or on another host, switch to Server mode.
• The sitekey and the page URL of the site you are automating.
• A Windmill variable holding the solver key, and a worker environment variable holding its address.

Why the import line is the whole install

Windmill parses the top-level imports when you save a script, works out which PyPI packages they map to, and spawns a dependency job that writes a lockfile. That lockfile is attached to the version of the script, so the deployment you tested is the deployment that runs six months later. There is no requirements file to maintain and nothing to install on the worker by hand.

You can pin the interpreter in the same place, with a comment in the script header. A deployed script that does not ask for a version runs on Python 3.11.

# py312
# pip install capskip - Windmill resolves this import itself
# and locks the version when the script is deployed.
from capskip import CapSkip

Step 1: the solve script

A Windmill script is a main function. Its arguments become the input schema and the form Windmill renders, so type them. Whatever you return is the script result, and a flow step downstream reads it from there.

# py312
# pip install capskip - resolved from this import on save.
import wmill
from capskip import CapSkip

def main(sitekey: str, page_url: str) -> str:
    # Host and port come from the worker environment. The key is
    # a Windmill variable, so it is stored encrypted and never
    # appears in the script body or in the run logs.
    solver = CapSkip(
        host=wmill.get_variable("u/admin/capskip_host"),
        port=8080,
        apiKey=wmill.get_variable("u/admin/capskip_key"),
    )

    result = solver.recaptcha(sitekey=sitekey, url=page_url)

    return result["code"]   # the token, for the next step

That is the entire integration for reCAPTCHA v2. Every other variant is the same method with an extra keyword: invisible set to 1, enterprise set to 1, or version set to v3 with an action name. Turnstile and GeeTest have their own methods with the same shape, and the full parameter list lives in the CapSkip API documentation.

Two things about the SDK are worth knowing before you reach for a hand-written polling loop. It does the polling for you, starting at 250 milliseconds and backing off rather than sleeping a flat interval, which usually beats the raw API’s published wait times. And its ceiling for reCAPTCHA, Turnstile and GeeTest is 300 seconds, set by recaptchaTimeout. That number matters when you set the script timeout in Step 4.

Step 2: keep the key in a Windmill variable

Windmill has first-class variables and secrets, and the script above reads one directly. There is a second way to do it that suits flows better: pass the variable in as a step argument using the reference syntax, and Windmill resolves it at run time with the caller’s permissions.

Those references resolve recursively, including inside lists and nested objects, so a step that takes a list of keys can hold a reference in each element. Give this workspace its own solver key rather than sharing one across everything you run.

Step 3: where the worker runs decides the connection mode

This is the question that actually shapes the setup, and it is easy to get wrong because the script looks identical either way. A Windmill worker is an autonomous process that runs one script at a time. It might be a container next to the database, a process on a VM, or a process on your own desktop. Whichever it is, the SDK call opens a socket from the worker, so the solver has to be reachable from there and nowhere else.

CapSkip has two connection modes for exactly this. Local binds to 127.0.0.1 and serves that device only. Server binds to your network address or public IP, so another box, a container host or a hosted platform can reach the same Windows machine over the API. Both are set under connection settings, and Server mode changes only where the solver runs. It is still your hardware and it is still unmetered.

Windmill workers do run on Windows, which is the case that keeps you on the loopback address. One setting matters there. PID namespace isolation defaults to true on Linux, and Windmill’s own documentation says to set it to false for Windows workers. Set the variable named ENABLE_UNSHARE_PID to false on a Windows worker and it starts normally.

For the other two rows, the address belongs in the worker environment rather than in the script. Windmill does not hand every host variable to a job by default, so name the ones you want in the variable called WHITELIST_ENVS on the worker, comma separated. A worker group can also carry its own static and dynamic environment variables, set in the UI, which is the tidier option when only some of your workers sit near the solver.

Step 4: the timeout and the retry

Windmill puts a Timeout field in a script’s runtime settings, next to Cache and Concurrency limits. Set it above your slowest solve, not below it. A reCAPTCHA v2 checkbox usually lands in well under a minute, but Turnstile challenge pages and GeeTest take longer, and the SDK will keep polling for up to 300 seconds before it gives up with a TimeoutException. A script timeout under that value turns a slow solve into a killed job with nothing useful in the log.

Once the script is a step in a flow, you get a second layer. Windmill flow steps retry in two shapes, and the exponential one suits a solver that is briefly busy.

The delay for the exponential shape is the multiplier times the base raised to the attempt number, so a base of 3 with a multiplier of 2 across five attempts spreads the waits from 6 seconds out to 486. There is also a Continue on error setting that lets the flow move on after the retries are exhausted and passes the error along as the step result, which is how you build a branch that falls back rather than failing the run.

Full working example

One script that solves and submits, so the token never sits around waiting for the next step. That last point is not stylistic. A reCAPTCHA token is good for about two minutes, and a flow that solves in one step, waits on an approval, then submits in another is the reliable way to lose it. There is more on that in the guide to reCAPTCHA token expiration.

# py312
# pip install capskip requests - both resolved from these imports.
import os
import requests
import wmill
from capskip import CapSkip
from capskip.exceptions import TimeoutException, NetworkException

SITE = "https://example.com/page-with-recaptcha"

def main(sitekey: str, username: str) -> dict:
    # CAPSKIP_HOST is set on the worker and allowed through by
    # WHITELIST_ENVS. It falls back to the loopback address so the
    # same script still runs on a worker that sits next to CapSkip.
    solver = CapSkip(
        host=os.environ.get("CAPSKIP_HOST", "127.0.0.1"),
        port=8080,
        apiKey=wmill.get_variable("u/admin/capskip_key"),
    )

    try:
        result = solver.recaptcha(sitekey=sitekey, url=SITE)
    except TimeoutException:
        # Let the flow's retry policy decide what happens next.
        raise
    except NetworkException:
        raise RuntimeError("CapSkip is unreachable from this worker")

    # Submit immediately. The token is short lived, and the field
    # name below is the one the page's own form posts.
    posted = requests.post(
        SITE,
        data={
            "username": username,
            "g-recaptcha-response": result["code"],
        },
        timeout=30,
    )

    return {"status": posted.status_code, "captcha_id": result["captchaId"]}

That last script returns the captcha id rather than the token, and that is deliberate. The id is useful when you are reading Windmill’s run history later, and the token is not: it has expired by then, and putting it in a stored job result puts it in your logs.

Solving several at once

A Windmill worker runs one script at a time, using the whole machine it has. So concurrency here is a matter of how many workers you run, not of what your script does. Two ways to get it, and they combine.

• Run more workers. A worker group can be scaled independently, and jobs are picked up by whichever worker is free.
• Solve in a batch inside one script. The Python SDK ships a genuine asynchronous client, so several solves can be in flight in a single job. That is worth doing when a run needs ten tokens rather than one, and the pattern is written up in the guide to solving CAPTCHAs in parallel with Python.

Set a concurrency limit on the script if the target site is the fragile part. CapSkip itself is not metered, so nothing about running more of these costs more, but the site you are automating may well notice.

Common errors and what they mean

FAQ

The short version

Import the SDK at the top of a Windmill script and let the dependency job pin it. Put the solver key in a Windmill variable and its address in a worker environment variable that WHITELIST_ENVS lets through. Decide the connection mode by asking where the worker runs, not where you sit: a worker on the solver’s own Windows box keeps Local mode, and everything else needs Server mode. Set the script timeout above 300 seconds, add exponential backoff at the flow step, and submit the token in the same job that produced it.

• The Python SDK itself is covered on the Python CAPTCHA solver page.
• The checkbox challenge is covered on the reCAPTCHA v2 solver page.
• The equivalent calls in Node.js, PHP and C# are listed on the CAPTCHA solving SDK page.

One thing to weigh before you schedule this every five minutes: CapSkip is a local captcha solver running on hardware you already own, so a flow that fires constantly and one that fires occasionally cost exactly the same.