A Temporal captcha solve goes in an Activity. Not in the workflow method, not in a helper the workflow calls, in an Activity. Workflow code is replayed from history every time the workflow resumes, so it has to be deterministic: no network calls, no randomness, no clock reads. A solve is all three of those things at once. Once it is in an Activity the rest is a retry policy and one piece of timing discipline, and the whole thing is about forty lines.<\/p>\n
# pip install temporalio\r\npip install -U temporalio capskip httpx\r\n\r\n# A local service to develop against.\r\ntemporal server start-dev<\/pre>\n<\/div>\nWhy the solve cannot live in workflow code<\/h2>\n
Temporal replays a workflow’s history to rebuild its state after a worker restart, a deploy or a week-long sleep. For that to produce the same answer twice, workflow code must be deterministic. The SDK is explicit about what that rules out: no network IO, no threading, no randomness, no external calls to processes, no global state mutation. It even runs workflow code in a sandbox that reimports modules per run, which is why activity imports get wrapped in a pass-through block.<\/p>\n
A CAPTCHA solve breaks the rule three times over. It is a network call, the token it returns is different on every attempt, and how long it takes depends on the machine. Put it in the workflow method and it will appear to work in development and produce a non-determinism error the first time a worker restarts mid-run.<\/p>\n
The good news is that this constraint hands you something. An Activity is retried by Temporal itself, with a policy you declare rather than a loop you write, and its result is recorded in history. So a solve that succeeded is never repeated on a replay, which is exactly what you want for something with a single-use answer.<\/p>\n
Step 1: the solve activity<\/h2>\n
Python’s CapSkip SDK ships a real asyncio client, not an alias, so an async activity is the natural fit and needs no thread pool. Take the sitekey and the page URL as arguments and return the token.<\/p>\n
\n# pip install capskip\r\nimport os\r\nfrom temporalio import activity\r\nfrom capskip import AsyncCapSkip\r\n\r\n@activity.defn\r\nasync def solve_recaptcha(sitekey: str, page_url: str) -> str:\r\n solver = AsyncCapSkip(\r\n host=os.environ.get("CAPSKIP_HOST", "127.0.0.1"),\r\n port=8080,\r\n apiKey=os.environ.get("CAPSKIP_API_KEY", "capskip"),\r\n )\r\n result = await solver.recaptcha(sitekey=sitekey, url=page_url)\r\n return result["code"]<\/pre>\n<\/div>\nOne method covers reCAPTCHA v2, Invisible, Enterprise and v3. The variants are options on the same call rather than separate methods: invisible set to 1, enterprise set to 1, or version set to v3 with an action. Turnstile and GeeTest have their own methods with the same shape, and the full parameter list is in the CapSkip API documentation<\/a>.<\/p>\n
If you would rather use the synchronous client, the activity has to be a plain def and the worker needs an activity_executor, because Temporal runs sync activities in a thread pool. The async version above avoids that entirely, which is one of the few places where the Python SDK is genuinely nicer than the others.<\/p>\n
Step 2: timeouts that are longer than the solver’s own<\/h2>\n
Every activity needs a start_to_close_timeout, and this is where people quietly break their own solves. CapSkip polls for up to 300 seconds on reCAPTCHA, Turnstile and GeeTest, and 120 seconds on image CAPTCHAs. Set the activity timeout below that and Temporal cancels the attempt while the solver is still working, then retries, and you have two solves in flight for one form.<\/p>\n
Give the activity headroom over the solver’s own limit. Six minutes against a five minute solver ceiling is comfortable.<\/p>\n
\n# Longer than recaptchaTimeout, which defaults to 300s.\r\nfrom datetime import timedelta\r\nfrom temporalio.common import RetryPolicy\r\n\r\nSOLVE_TIMEOUT = timedelta(minutes=6)\r\n\r\nSOLVE_RETRIES = RetryPolicy(\r\n initial_interval=timedelta(seconds=5),\r\n backoff_coefficient=2.0,\r\n maximum_attempts=4,\r\n # These fail identically every time. Do not burn attempts.\r\n non_retryable_error_types=["ValidationException", "ApiException"],\r\n)<\/pre>\n<\/div>\nThe non-retryable list is matched by exception class name, and it is worth filling in. ValidationException means a missing or malformed argument, and ApiException means the API rejected the request, usually a sitekey that does not belong to the page URL. Neither improves on the second attempt. NetworkException and TimeoutException are the two that genuinely deserve a retry: the first means the solver is not running or the host is wrong, the second means the solve outlasted the polling timeout. All four derive from a common base, so catching CapSkipError works if you would rather handle everything in one place.<\/p>\n
Step 3: solve last, not first<\/h2>\n
Durable execution makes token expiry easier to get wrong here than in any other orchestrator. A Temporal workflow can wait for a signal, sleep for a day and carry on, and its recorded activity results come back from history unchanged. So a workflow that solves early, waits for an approval, then submits will replay a token that was minted yesterday.<\/p>\n
A reCAPTCHA token is accepted once and expires in about two minutes. Order the workflow so the solve is the step immediately before the submit, with nothing that can block in between. The general shape of that problem is covered in the guide to reCAPTCHA token expiration<\/a>.<\/p>\n
Full working example<\/h2>\n
Three activities and a workflow that calls them in order. Read the sitekey, solve, submit. Each activity gets its own timeout and its own retry policy, and each one shows up separately in the Temporal UI, so when something is slow you can see which step it was.<\/p>\n
\n# activities.py\r\nimport os, re, httpx\r\nfrom temporalio import activity\r\nfrom capskip import AsyncCapSkip\r\n\r\n@activity.defn\r\nasync def read_sitekey(page_url: str) -> str:\r\n async with httpx.AsyncClient(timeout=30) as client:\r\n html = (await client.get(page_url)).text\r\n found = re.search(r'data-sitekey=["\\']([^"\\']+)', html)\r\n if not found:\r\n raise RuntimeError("No data-sitekey on the page.")\r\n return found.group(1)\r\n\r\n@activity.defn\r\nasync def solve_recaptcha(sitekey: str, page_url: str) -> str:\r\n solver = AsyncCapSkip(host=os.environ.get("CAPSKIP_HOST", "127.0.0.1"))\r\n return (await solver.recaptcha(sitekey=sitekey, url=page_url))["code"]\r\n\r\n@activity.defn\r\nasync def submit_form(page_url: str, token: str) -> int:\r\n async with httpx.AsyncClient(timeout=30) as client:\r\n reply = await client.post(\r\n page_url, data={"g-recaptcha-response": token}\r\n )\r\n return reply.status_code<\/pre>\n<\/div>\nThe workflow itself holds no logic beyond the ordering. That is the point: everything that can fail is in an activity, and the workflow is the deterministic part that survives a replay.<\/p>\n
\n# workflow.py\r\nfrom datetime import timedelta\r\nfrom temporalio import workflow\r\nfrom temporalio.common import RetryPolicy\r\n\r\nwith workflow.unsafe.imports_passed_through():\r\n from activities import read_sitekey, solve_recaptcha, submit_form\r\n\r\n@workflow.defn\r\nclass SubmitProtectedForm:\r\n @workflow.run\r\n async def run(self, page_url: str) -> int:\r\n sitekey = await workflow.execute_activity(\r\n read_sitekey, page_url,\r\n start_to_close_timeout=timedelta(seconds=60),\r\n )\r\n # Solve directly before the submit. Tokens go stale.\r\n token = await workflow.execute_activity(\r\n solve_recaptcha, args=[sitekey, page_url],\r\n start_to_close_timeout=timedelta(minutes=6),\r\n retry_policy=RetryPolicy(\r\n maximum_attempts=4,\r\n non_retryable_error_types=["ValidationException"],\r\n ),\r\n )\r\n return await workflow.execute_activity(\r\n submit_form, args=[page_url, token],\r\n start_to_close_timeout=timedelta(seconds=60),\r\n )<\/pre>\n<\/div>\nNote the args list on the two-argument activities. A single positional argument can be passed directly, but more than one has to go through args, and getting that wrong is the most common first error in this SDK.<\/p>\n
\n# worker.py - run this where CapSkip can be reached\r\nimport asyncio\r\nfrom temporalio.client import Client\r\nfrom temporalio.worker import Worker\r\nfrom activities import read_sitekey, solve_recaptcha, submit_form\r\nfrom workflow import SubmitProtectedForm\r\n\r\nasync def main():\r\n client = await Client.connect("localhost:7233")\r\n worker = Worker(\r\n client,\r\n task_queue="captcha-queue",\r\n workflows=[SubmitProtectedForm],\r\n activities=[read_sitekey, solve_recaptcha, submit_form],\r\n )\r\n await worker.run()\r\n\r\nasyncio.run(main())<\/pre>\n<\/div>\nWhere the worker runs, and where the solver runs<\/h2>\n
Temporal splits the two cleanly, and it works in your favour. The Temporal Service schedules work and stores history. It never executes your code. A worker you start inside your own infrastructure holds a long outbound connection to the service and picks tasks off a queue. Nothing inbound is ever opened to your network.<\/p>\n
So a worker on the same Windows machine as CapSkip calls 127.0.0.1:8080 exactly as a script on your desk would, and that stays true on Temporal Cloud. The cloud in Temporal Cloud is the orchestration layer, not the compute layer.<\/p>\n
The moment the worker moves, the host changes and nothing else does. A worker in a container, on a Linux VM or in Kubernetes cannot reach a Windows solver over loopback, so the solver switches to Server mode. Local mode binds to 127.0.0.1 and answers that device only. Server mode binds to your network or public IP, and a static public IP keeps the address stable. It is still your hardware and still unmetered in both modes, so a workflow that runs ten thousand times a day costs the same as one that runs once.<\/p>\n
\n# One environment variable, no code change.\r\n# CAPSKIP_HOST=10.0.0.12 on the worker.\r\nsolver = AsyncCapSkip(host=os.environ["CAPSKIP_HOST"], port=8080)<\/pre>\n<\/div>\nTurn key validation on once the solver listens on a network address, and give each worker fleet its own key so one can be revoked without touching the others. Both modes are walked through in the CapSkip setup guide<\/a>.<\/p>\n
Common errors and what they mean<\/h2>\n