An Apify captcha step is the usual three moves, plus one that is specific to the platform. Read the sitekey, solve it, post the token back with the form. The extra move is deciding where the solver lives, because an Actor does not run on your laptop. It runs in a container on Apify’s infrastructure, so the loopback address inside it belongs to that container and nothing else. Get that one decision right and the rest is twenty lines.<\/p>\n
# Scaffold an Actor, then add the solver client.\napify create captcha-actor -t getting_started_node\ncd captcha-actor\nnpm install capskip<\/pre>\n<\/div>\nServer mode is not optional here<\/h2>\n
This is the part that trips people up, so it goes first. Actors execute on Apify’s workers. When your Actor code opens a connection to 127.0.0.1:8080 it is talking to its own container, which is not running a solver, and the call fails with a connection error that looks like the solver crashed. Nothing crashed. The address was simply local to the wrong machine.<\/p>\n
CapSkip has two connection modes for exactly this reason. Local binds to 127.0.0.1 and answers only that device. Server binds to your network or public IP, so another box, a VPS or a hosted platform such as Apify can call the same solver over the API. A static public IP keeps the address stable between runs.<\/p>\n
Worth saying plainly, because it comes up: Server mode does not turn CapSkip into a metered cloud service. It is still your machine and still unlimited. All that changes is which interface it listens on. Once it is listening on a network address, switch key validation on and give the Actor its own key, so that key can be revoked without disturbing anything else.<\/p>\n
Step 1: declare the solver address as a secret input<\/h2>\n
Do not hardcode the host. Apify’s input schema supports encrypted fields, which is the right home for a solver address and its key, and it means the values are set per run rather than baked into a build. Encryption works with the textfield, textarea and hidden editors.<\/p>\n
\n{\n "title": "CAPTCHA actor input",\n "type": "object",\n "schemaVersion": 1,\n "properties": {\n "targetUrl": {\n "title": "Target URL",\n "type": "string",\n "editor": "textfield"\n },\n "solverHost": {\n "title": "Solver host",\n "type": "string",\n "editor": "textfield",\n "isSecret": true\n },\n "solverKey": {\n "title": "Solver API key",\n "type": "string",\n "editor": "textfield",\n "isSecret": true\n }\n },\n "required": ["targetUrl", "solverHost"]\n}<\/pre>\n<\/div>\nThat file goes in the .actor folder next to actor.json, and the values arrive in your code through the input object.<\/p>\n
Step 2: pick the host at runtime<\/h2>\n
You want one Actor that works in both places: talking to 127.0.0.1 while you run it locally, and talking to your server once it is deployed. The SDK exposes a boolean for precisely this. Actor.isAtHome() returns true when the code is executing on the Apify platform and false when it is not.<\/p>\n
\n\/\/ npm install apify capskip\nimport { Actor } from 'apify';\nimport { CapSkip } from 'capskip';\n\nawait Actor.init();\nconst input = await Actor.getInput();\n\n\/\/ Local run talks to the loopback address. A platform run\n\/\/ talks to the server address that came in as a secret.\nconst solver = new CapSkip({\n host: Actor.isAtHome() ? input.solverHost : '127.0.0.1',\n port: 8080,\n apiKey: input.solverKey,\n});<\/pre>\n<\/div>\nNothing else in the Actor has to know about the difference. The same code path handles both, and a failed deploy no longer means editing constants.<\/p>\n
Step 3: read the sitekey, solve it, post the token<\/h2>\n
The sitekey sits on the host document as a data-sitekey attribute, so a plain fetch and a regular expression get it without starting a browser. That matters on a paid platform: an Actor with no browser needs far less memory, and Apify bills on memory multiplied by time. Actor.fail() below ends the run rather than returning, which is why the code after it can assume the match succeeded.<\/p>\n
\n\/\/ Fetch the form page and lift the sitekey out of it.\nconst html = await (await fetch(input.targetUrl)).text();\nconst match = html.match(\/data-sitekey="([^"]+)"\/);\n\nif (!match) {\n await Actor.fail('No sitekey on the page. Did the widget render?');\n}\n\nconst result = await solver.recaptcha(match[1], input.targetUrl);\nconst token = result.code; \/\/ the g-recaptcha-response value<\/pre>\n<\/div>\nThen submit the form with the token in the field the site expects. For reCAPTCHA v2 the hidden textarea is named g-recaptcha-response, and most forms post it under that same name. If the page hands the token to a callback instead, check what the callback actually submits.<\/p>\n
\n\/\/ The token travels as an ordinary form field.\nconst body = new URLSearchParams({\n email: 'someone@example.com',\n 'g-recaptcha-response': token,\n});\n\nconst posted = await fetch(input.targetUrl, { method: 'POST', body });\nawait Actor.pushData({ url: input.targetUrl, status: posted.status });<\/pre>\n<\/div>\nTurnstile and GeeTest have their own methods on the same client, and both take the same shape. Turnstile also returns a user agent that has to be sent with the token on challenge pages. Full parameter lists are in the CapSkip API documentation<\/a>.<\/p>\n
Full working example<\/h2>\n
The whole Actor, as src\/main.js. An Actor is an ES module with top-level await, so there is no wrapper function, and Actor.exit() at the end is what flushes the dataset and closes the run cleanly.<\/p>\n
\n\/\/ npm install apify capskip\nimport { Actor } from 'apify';\nimport { CapSkip, NetworkException, TimeoutException } from 'capskip';\n\nawait Actor.init();\n\nconst input = await Actor.getInput();\nconst solver = new CapSkip({\n host: Actor.isAtHome() ? input.solverHost : '127.0.0.1',\n port: 8080,\n apiKey: input.solverKey,\n});\n\ntry {\n const html = await (await fetch(input.targetUrl)).text();\n const match = html.match(\/data-sitekey="([^"]+)"\/);\n if (!match) throw new Error('No sitekey found on the page.');\n\n const result = await solver.recaptcha(match[1], input.targetUrl);\n\n const body = new URLSearchParams({\n 'g-recaptcha-response': result.code,\n });\n const posted = await fetch(input.targetUrl, { method: 'POST', body });\n\n await Actor.pushData({ url: input.targetUrl, status: posted.status });\n} catch (err) {\n if (err instanceof NetworkException) {\n await Actor.fail('Cannot reach the solver. Check Server mode and the host.');\n }\n if (err instanceof TimeoutException) {\n await Actor.fail('The solve outlasted recaptchaTimeout.');\n }\n throw err;\n}\n\nawait Actor.exit();<\/pre>\n<\/div>\nCatching the two connection-shaped exceptions separately is worth the six lines. Actor.fail() is Actor.exit() with an exit code of 1 and a message attached, so the run ends as FAILED with a sentence in the log that tells you which half of the setup broke. Without it, a solver that is simply unreachable and a solve that genuinely could not be read produce the same red run.<\/p>\n
Running it locally before you deploy<\/h2>\n
Run the Actor on your own machine first, with the solver in Local mode. isAtHome() returns false there, so the code reaches for 127.0.0.1 without you changing anything, and you get to prove the sitekey read and the form post work before adding the network hop.<\/p>\n
\n# Reads INPUT from storage\/key_value_stores\/default.\napify run<\/pre>\n<\/div>\nWhen that passes, switch CapSkip to Server mode, note the address it now listens on, and put that address in the solverHost input on the platform. The only thing that changed is one string.<\/p>\n
Common errors and what they mean<\/h2>\n