To solve reCAPTCHA in Bun, add the CapSkip Node.js SDK with bun add. Build the client from values that Bun has already loaded from your .env file, then call the solver and post the token. CapSkip runs on your own Windows PC, so there is no per-solve bill. The code is short, and the SDK works under Bun as it is. Three Bun habits are not what a Node developer expects. Bun reads .env files without being asked, and only from the folder you run it in. A timeout on a hung socket rejects but does not end the process. And bun test stops every test after five seconds, which is shorter than a real solve. This guide covers each of them.<\/p>\n
The measurements below come from a mock CapSkip and a mock login page on the same PC. Bun and the SDK are the real ones. Bun and the SDK should behave the same against your own site, but only a mock was used. Solve times and the accept and reject rules of the login page are the mock’s own.<\/p>\n
Bun’s own installation page gives the command below, and it also lists npm install -g bun. The tests for this guide used Bun 1.4.3 installed through npm into a project folder. The installer command itself was not run here. Open a new PowerShell window afterwards, so that PATH is refreshed.<\/p>\n
# PowerShell: Bun's official installer (or: npm install -g bun)\npowershell -c "irm bun.sh\/install.ps1|iex"\n\n# Open a new PowerShell window so PATH is refreshed, then check:\nbun --version<\/pre>\n<\/div>\nStep 2: create the project first<\/h2>\n
Run bun init before bun add. If the folder has no package.json, bun add looks upward for the nearest one and changes that file instead. On a test folder inside a decoy parent, it kept the parent’s other packages and added capskip to the parent. Your own parent folder could be a profile folder or a monorepo root. Creating the project file first keeps the install where you expect.<\/p>\n
\n# Make the folder, then create package.json BEFORE bun add.\nmkdir captcha-bun\ncd captcha-bun\nbun init -y\nbun add capskip<\/pre>\n<\/div>\nThe init command writes a strict tsconfig.json, an index.ts, a README.md, a .gitignore and a package.json with the module type set. It also installs TypeScript and the Bun type definitions. The add command saves capskip as version 1.3.0 or later and writes a text lockfile named bun.lock. The SDK is CommonJS. Both the named import used below and require work, which is different from Deno, where require fails.<\/p>\n
Skipping the init has a second cost. Bun resolves an import by walking up the folders. With no node_modules in your project, it loaded an older capskip 1.0.2 from a node_modules in a parent folder on the test PC. No error said so.<\/p>\n
Step 3: put the settings in a .env file<\/h2>\n
Create a file called .env in the project folder. Bun loads it before your code runs, so the values are in Bun.env and process.env, and the two always agree. The SDK reads no environment variable itself. Your script reads the three values and passes them in, which is the next step. The LOGIN_URL line is for the live test further down.<\/p>\n
\n# .env in the folder you run bun from (bun init already git-ignores it)\nCAPSKIP_HOST=127.0.0.1\nCAPSKIP_PORT=8080\nCAPSKIP_API_KEY=capskip\nLOGIN_URL=https:\/\/example.com\/login<\/pre>\n<\/div>\nKnow the rules, because a stray .env file can surprise you:<\/p>\n
\n
- Bun reads .env files only from the folder you run it in. Running a script by path from another folder reads nothing, and a .env one folder up is not read either.<\/li>\n
- A variable set in the shell wins. Then come .env.local, then the file for the mode, which is .env.development under bun run unless NODE_ENV is set, and then plain .env.<\/li>\n
- The bun init .gitignore covers .env and .env.local. It does not cover .env.production, .env.test or .env.development, so add them before you commit.<\/li>\n
- Quotes, a trailing comment and ${OTHER} expansion work in the file.<\/li>\n<\/ul>\n
Step 4: build the CapSkip client<\/h2>\n
Save the next blocks one after another in a file called solve.ts. Steps 4 to 9 all go into that one file, and the whole file is shown near the end. The defaults make the script run with no setup. CAPSKIP_API_KEY only matters if you switched on API key validation in CapSkip.<\/p>\n
\nimport {\n ApiException,\n CapSkip,\n NetworkException,\n TimeoutException,\n} from "capskip";\n\n\/\/ Bun has already loaded .env into Bun.env. The SDK reads no\n\/\/ environment variable itself, so pass the three values in.\nconst solver = new CapSkip({\n host: Bun.env.CAPSKIP_HOST ?? "127.0.0.1",\n port: Number(Bun.env.CAPSKIP_PORT ?? 8080),\n apiKey: Bun.env.CAPSKIP_API_KEY ?? "capskip",\n});<\/pre>\n<\/div>\nStep 5: keep cookies yourself<\/h2>\n
The login form needs the cookie from the page that showed it, and fetch in Bun keeps no cookies. Read every Set-Cookie line with getSetCookie. The usual headers.get call joins the lines with a comma, and the comma inside an Expires date then breaks the split.<\/p>\n
\n\/\/ fetch keeps no cookies, so collect every Set-Cookie line.\n\/\/ (headers.get("set-cookie") would glue them into one string.)\nconst jar = new Map<string, string>();\n\nfunction keepCookies(response: Response): void {\n for (const line of response.headers.getSetCookie()) {\n const pair = line.split(";")[0] ?? "";\n const eq = pair.indexOf("=");\n jar.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());\n }\n}\n\nconst cookies = () =>\n Array.from(jar, ([name, value]) => `${name}=${value}`).join("; ");<\/pre>\n<\/div>\nStep 6: read the sitekey and the CSRF token<\/h2>\n
This part is yours, not CapSkip’s. It opens the login page and pulls out the two values. Adjust the patterns to your markup.<\/p>\n
\n\/\/ Load the login page, keep its cookies, and read the sitekey and\n\/\/ the CSRF token. Adjust the two patterns to your page's markup.\nasync function loadForm(pageUrl: string) {\n const page = await fetch(pageUrl);\n keepCookies(page);\n const html = await page.text();\n\n const sitekey = html.match(\/data-sitekey="([^"]+)"\/)?.[1];\n const csrf = html.match(\/name="csrfmiddlewaretoken" value="([^"]+)"\/)?.[1];\n if (!sitekey || !csrf) throw new Error("sitekey or CSRF token not found");\n return { sitekey, csrf };\n}<\/pre>\n<\/div>\nStep 7: add a timeout that works<\/h2>\n
The SDK sets no socket timeout. A CapSkip that accepts the call and never answers hangs the script. In testing, Bun printed nothing and never exited, and it was still waiting after 400 seconds. The SDK’s timeout option is checked between polls only, so it cannot help while a single request is stuck. The block below races the solve against a timer.<\/p>\n
\n\/\/ The SDK sets no socket timeout, so a CapSkip that accepts the call\n\/\/ and never answers would hang the script. Race the solve against a\n\/\/ timer. In Bun an AbortSignal.timeout does not keep the process alive.\nfunction withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {\n const signal = AbortSignal.timeout(ms);\n const limit = new Promise<never>((_, reject) => {\n signal.addEventListener("abort", () =>\n reject(new TimeoutException(`no answer from CapSkip in ${ms} ms`)),\n );\n });\n return Promise.race([work, limit]);\n}\n\n\/\/ The SDK gives up after 300 s by itself, so 330 s only fires when\n\/\/ CapSkip goes silent. code is typed "string or object", hence String().\nasync function getToken(sitekey: string, pageUrl: string): Promise<string> {\n const solving = solver.recaptcha(sitekey, pageUrl);\n const { code } = await withTimeout(solving, 330_000);\n return String(code);\n}<\/pre>\n<\/div>\nBun differs from Deno here, in your favour. A timer from AbortSignal.timeout does not keep Bun alive, so a normal solve still exits as soon as it is done. In testing, a script with a 330 second budget around a 1.8 second solve ended at about 1.8 seconds. A plain setTimeout that you never clear is a different matter. It kept Bun alive until it fired, 20.04 seconds for a 20 second budget. Clear such a timer in a finally block or use the signal.<\/p>\n
The catch is the other direction. When the budget runs out on a hung socket, the promise rejects at once, at 3.0 seconds in a test with a 3 second budget. Then Bun stays alive, because the stuck socket holds it open. That is why Step 9 ends with process.exit. The same happens when the race is lost while CapSkip is still answering not ready. The SDK keeps polling in the background, and the process lives until the SDK’s own timeout, which was 12.8 seconds with a limit of 12.<\/p>\n
Pick a smaller budget if your script should fail faster. The tests ran the block with 4 seconds and a CapSkip that went silent on the submit, and then on the poll. Both printed the message from Step 9 and exited with code 1 at about 4.04 seconds. A normal solve exited with code 0 at about 1.8 seconds.<\/p>\n
Step 8: solve, post and check the result<\/h2>\n
The next block is the login. A reCAPTCHA token works once, so each login solves its own. Two details matter. A strict site such as Django over HTTPS rejects a form post that has no Referer, and fetch sends none, so the block sets it. And fetch follows a 302 by default and drops the new cookie on the way. So the block sets redirect to manual and reads the cookie from the 302. Change the field names, the username and the Welcome back marker to match your site.<\/p>\n
\n\/\/ fetch sends no Referer, and a strict site rejects the post without\n\/\/ one. redirect "manual" keeps the 302 so we can read its new cookie.\nexport async function login(pageUrl: string): Promise<boolean> {\n jar.clear();\n const { sitekey, csrf } = await loadForm(pageUrl);\n const token = await getToken(sitekey, pageUrl);\n\n const response = await fetch(pageUrl, {\n method: "POST",\n redirect: "manual",\n headers: { Cookie: cookies(), Referer: pageUrl },\n body: new URLSearchParams({\n csrfmiddlewaretoken: csrf,\n username: "YOUR_USERNAME",\n password: "YOUR_PASSWORD",\n "g-recaptcha-response": token,\n }),\n });\n keepCookies(response);\n if (response.status !== 302) {\n const body = await response.text();\n throw new Error(`login rejected: ${response.status} ${body}`);\n }\n\n \/\/ Swap "Welcome back" for a marker your own site shows after login.\n const next = new URL(response.headers.get("location") ?? "\/", pageUrl);\n const home = await fetch(next, { headers: { Cookie: cookies() } });\n return (await home.text()).includes("Welcome back");\n}<\/pre>\n<\/div>\nStep 9: report errors and run it<\/h2>\n
A closed port, an error from CapSkip and a slow solve are three different exception classes, and instanceof tells them apart under Bun. A closed port raised NetworkException in about 10 milliseconds with the message connect ECONNREFUSED 127.0.0.1 and the port. The host name localhost was nearly as fast but left the message empty, with the error code on the cause. The block falls back to that code.<\/p>\n
\n\/\/ A closed port, a bad reply and a slow solve are three different\n\/\/ exception classes. A host NAME can leave the message empty, so fall\n\/\/ back to the error code on .cause.\nfunction explain(err: unknown): string {\n if (err instanceof NetworkException) {\n const code = (err.cause as { code?: string } | undefined)?.code;\n return `CapSkip is not reachable: ${err.message || code}`;\n }\n if (err instanceof ApiException) return `CapSkip replied: ${err.message}`;\n if (err instanceof TimeoutException) return `Too slow: ${err.message}`;\n return err instanceof Error ? (err.stack ?? err.message) : String(err);\n}\n\n\/\/ import.meta.main is true only when this file is run directly, so\n\/\/ the tests can import login() without starting a login.\nif (import.meta.main) {\n try {\n const ok = await login(Bun.argv[2] ?? "https:\/\/example.com\/login");\n console.log(ok ? "logged in" : "NOT logged in");\n process.exit(ok ? 0 : 2);\n } catch (err) {\n console.error(explain(err));\n \/\/ A hung socket would keep Bun alive, so leave explicitly.\n process.exit(1);\n }\n}<\/pre>\n<\/div>\nReplace the example URL with your own login page, and run it from the project folder. Bun picks up the .env file there. A variable set in PowerShell beats the same name in the file, and it stays set for the rest of that PowerShell session, so the block clears it again. The last two commands switch the automatic loading off, or read a file of your choosing instead. Create that file first. A missing file is skipped without a message, and .env is not read either.<\/p>\n
\n# Run it. Bun reads .env from the folder you run this in.\nbun run solve.ts https:\/\/example.com\/login\n\n# A variable set in PowerShell beats the same name in .env.\n$env:CAPSKIP_API_KEY = "my-key"\nbun run solve.ts https:\/\/example.com\/login\nRemove-Item Env:CAPSKIP_API_KEY\n\n# Ignore .env completely, or read a different file instead. The second\n# file must exist: a missing one is skipped and .env is not read either.\nbun run --no-env-file solve.ts https:\/\/example.com\/login\nbun run --env-file=.env.office solve.ts https:\/\/example.com\/login<\/pre>\n<\/div>\nA good run prints logged in and exits with code 0. Against the mock, a solve that the mock held for one second took 1.77 seconds. The SDK polls at once, then waits 0.25, 0.5, 1, 2 and 4 seconds, and 5 seconds after that. A short solve is not rounded up to a flat five.<\/p>\n
Test it with bun test<\/h2>\n
Bun ships its own test runner. It runs files named like solve.test.ts, and its default limit is 5000 milliseconds per test. A real reCAPTCHA solve can take longer. A test that waited for the 8 second mock failed with this, and the run exited with code 1:<\/p>\n
\n
- (fail) logs in through CapSkip [5001.15ms]<\/li>\n
- this test timed out after 5000ms.<\/li>\n<\/ul>\n
Raise the limit in one of three ways: the third argument of test, setDefaultTimeout as below, or the timeout switch of bun test. All three passed against the 8 second mock. A timeout key under the test heading of bunfig.toml did not work. The test still failed at 5000 milliseconds, and Bun’s bunfig documentation lists no such key. The live test reads LOGIN_URL from the .env file, so set it to your login page. Save this one as solve.test.ts.<\/p>\n
\nimport { expect, setDefaultTimeout, test } from "bun:test";\nimport { login } from ".\/solve";\n\n\/\/ bun test stops every test after 5 s, and a real solve can take\n\/\/ longer. Raise the limit for the whole file (or pass a number as the\n\/\/ third argument of test(), or run: bun test --timeout 120000).\nsetDefaultTimeout(120_000);\n\ntest("logs in through CapSkip", async () => {\n const ok = await login(Bun.env.LOGIN_URL ?? "https:\/\/example.com\/login");\n expect(ok).toBe(true);\n});<\/pre>\n<\/div>\nMost of your suite should not need a solver at all. The second test replaces the SDK with a fake and runs against a small stand-in site, so it passes with CapSkip closed. Two things are easy to get wrong. The import of solve.ts must be dynamic, because a static import runs before mock.module does. And the fake leaks. The mock stays in force for the other test files. Plain bun test made solve.test.ts fail with login rejected: 403, because it was now using the fake solver. Save this one as fake.test.ts.<\/p>\n
\nimport { expect, mock, test } from "bun:test";\n\n\/\/ Replace the SDK before solve.ts loads it. The import must be dynamic,\n\/\/ because a static import runs before mock.module() does.\nmock.module("capskip", () => ({\n CapSkip: class {\n async recaptcha() {\n return { captchaId: "1", code: "fake-token" };\n }\n },\n ApiException: class extends Error {},\n NetworkException: class extends Error {},\n TimeoutException: class extends Error {},\n}));\nconst { login } = await import(".\/solve");\n\n\/\/ A tiny stand-in login site: it only accepts the fake token.\nconst site = Bun.serve({\n port: 0,\n async fetch(req) {\n const url = new URL(req.url);\n if (req.method === "GET" && url.pathname === "\/login") {\n return new Response(\n '<div data-sitekey="K"><\/div>' +\n '<input name="csrfmiddlewaretoken" value="C">',\n );\n }\n if (req.method === "POST") {\n const form = await req.formData();\n if (form.get("g-recaptcha-response") !== "fake-token")\n return new Response("bad token", { status: 403 });\n return new Response(null, {\n status: 302,\n headers: { Location: "\/home" },\n });\n }\n return new Response("Welcome back");\n },\n});\n\ntest("login posts the token CapSkip returned", async () => {\n expect(await login(`http:\/\/127.0.0.1:${site.port}\/login`)).toBe(true);\n await site.stop();\n});<\/pre>\n<\/div>\nThe fix is the isolate switch, which gives each file a fresh global object. With it, both files passed. Bun also sets NODE_ENV to test during bun test, so it loads .env.test and skips .env.local.<\/p>\n
\n# Run every *.test.ts file. --isolate gives each file a fresh global\n# object, so the fake SDK in fake.test.ts cannot leak into the others.\nbun test --isolate\n\n# The default limit is 5 s per test. Raise it for all tests (ms).\nbun test --isolate --timeout 120000<\/pre>\n<\/div>\nBuild one .exe<\/h2>\n
The compile command puts the Bun runtime, your script and the SDK in a single file. It took 0.3 seconds here and made a file of 96.4 MB, the size of Bun itself. The exe ran with a PATH that had no Bun on it. The .env file is not baked in. The exe reads the .env of the folder it runs from, at run time. It does not use the one from the build folder or the one next to the exe. Started from a folder with no .env, the port comes back undefined, and the defaults in Step 4 apply. In Task Scheduler, set the Start in folder to the one with your .env. Add the no-compile-autoload-dotenv switch to the build command and the exe ignores the file. Real variables still work.<\/p>\n
\n# One .exe with the Bun runtime and the SDK inside. Run it from the\n# folder that holds your .env (Task Scheduler: set "Start in").\nbun build --compile --outfile solve.exe solve.ts\n.\\solve.exe https:\/\/example.com\/login<\/pre>\n<\/div>\nCheck the types on demand<\/h2>\n
The bun run command strips types and never checks them. A file with a type error still ran and logged in. Bun 1.4.3 has a bun check command that runs TypeScript over the project, and both test files were clean. Three typing details of the SDK are worth knowing. The code field is declared as a string or an object, which is why Step 7 wraps it in String. The token field is optional. And the options type of the recaptcha call accepts any name, so a misspelled option compiles. A misspelled constructor option such as hots is an error.<\/p>\n
\n# bun run never type checks. Check on demand (TypeScript from bun init):\nbun check<\/pre>\n<\/div>\nRun the script against CapSkip on another machine<\/h2>\n
The script and the solver do not have to share a PC. Switch CapSkip to Server mode under connection settings, and it listens on your network address or public IP. Put that address in the .env of the machine that runs the script. A static public IP is recommended for stable remote access. The solver is still your own Windows machine, and solves are still unmetered.<\/p>\n
\n# .env on the PC that runs the script, with CapSkip in Server mode\n# on another PC. Use that PC's address, and an API key if you set one.\nCAPSKIP_HOST=192.168.1.50\nCAPSKIP_PORT=8080\nCAPSKIP_API_KEY=your-long-random-key<\/pre>\n<\/div>\nMind two things. The SDK talks to CapSkip over plain HTTP, so the API key travels in clear text. Keep that link on a private network or a VPN, and turn on API key validation. And CapSkip opens its port to every address when Server mode starts. To limit access to the machines you expect, add a Windows Firewall block rule for the others. The remote setup was not run for this guide. Only the .env file was parsed.<\/p>\n
The whole solve.ts<\/h2>\n
This is Steps 4 to 9 in one file, for a quick start. If you saved the blocks one by one, you already have it. Do not paste the file twice, or Bun reports that a name is already declared.<\/p>\n
\nimport {\n ApiException,\n CapSkip,\n NetworkException,\n TimeoutException,\n} from "capskip";\n\n\/\/ Bun has already loaded .env into Bun.env. The SDK reads no\n\/\/ environment variable itself, so pass the three values in.\nconst solver = new CapSkip({\n host: Bun.env.CAPSKIP_HOST ?? "127.0.0.1",\n port: Number(Bun.env.CAPSKIP_PORT ?? 8080),\n apiKey: Bun.env.CAPSKIP_API_KEY ?? "capskip",\n});\n\n\/\/ fetch keeps no cookies, so collect every Set-Cookie line.\n\/\/ (headers.get("set-cookie") would glue them into one string.)\nconst jar = new Map<string, string>();\n\nfunction keepCookies(response: Response): void {\n for (const line of response.headers.getSetCookie()) {\n const pair = line.split(";")[0] ?? "";\n const eq = pair.indexOf("=");\n jar.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());\n }\n}\n\nconst cookies = () =>\n Array.from(jar, ([name, value]) => `${name}=${value}`).join("; ");\n\n\/\/ Load the login page, keep its cookies, and read the sitekey and\n\/\/ the CSRF token. Adjust the two patterns to your page's markup.\nasync function loadForm(pageUrl: string) {\n const page = await fetch(pageUrl);\n keepCookies(page);\n const html = await page.text();\n\n const sitekey = html.match(\/data-sitekey="([^"]+)"\/)?.[1];\n const csrf = html.match(\/name="csrfmiddlewaretoken" value="([^"]+)"\/)?.[1];\n if (!sitekey || !csrf) throw new Error("sitekey or CSRF token not found");\n return { sitekey, csrf };\n}\n\n\/\/ The SDK sets no socket timeout, so a CapSkip that accepts the call\n\/\/ and never answers would hang the script. Race the solve against a\n\/\/ timer. In Bun an AbortSignal.timeout does not keep the process alive.\nfunction withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {\n const signal = AbortSignal.timeout(ms);\n const limit = new Promise<never>((_, reject) => {\n signal.addEventListener("abort", () =>\n reject(new TimeoutException(`no answer from CapSkip in ${ms} ms`)),\n );\n });\n return Promise.race([work, limit]);\n}\n\n\/\/ The SDK gives up after 300 s by itself, so 330 s only fires when\n\/\/ CapSkip goes silent. code is typed "string or object", hence String().\nasync function getToken(sitekey: string, pageUrl: string): Promise<string> {\n const solving = solver.recaptcha(sitekey, pageUrl);\n const { code } = await withTimeout(solving, 330_000);\n return String(code);\n}\n\n\/\/ fetch sends no Referer, and a strict site rejects the post without\n\/\/ one. redirect "manual" keeps the 302 so we can read its new cookie.\nexport async function login(pageUrl: string): Promise<boolean> {\n jar.clear();\n const { sitekey, csrf } = await loadForm(pageUrl);\n const token = await getToken(sitekey, pageUrl);\n\n const response = await fetch(pageUrl, {\n method: "POST",\n redirect: "manual",\n headers: { Cookie: cookies(), Referer: pageUrl },\n body: new URLSearchParams({\n csrfmiddlewaretoken: csrf,\n username: "YOUR_USERNAME",\n password: "YOUR_PASSWORD",\n "g-recaptcha-response": token,\n }),\n });\n keepCookies(response);\n if (response.status !== 302) {\n const body = await response.text();\n throw new Error(`login rejected: ${response.status} ${body}`);\n }\n\n \/\/ Swap "Welcome back" for a marker your own site shows after login.\n const next = new URL(response.headers.get("location") ?? "\/", pageUrl);\n const home = await fetch(next, { headers: { Cookie: cookies() } });\n return (await home.text()).includes("Welcome back");\n}\n\n\/\/ A closed port, a bad reply and a slow solve are three different\n\/\/ exception classes. A host NAME can leave the message empty, so fall\n\/\/ back to the error code on .cause.\nfunction explain(err: unknown): string {\n if (err instanceof NetworkException) {\n const code = (err.cause as { code?: string } | undefined)?.code;\n return `CapSkip is not reachable: ${err.message || code}`;\n }\n if (err instanceof ApiException) return `CapSkip replied: ${err.message}`;\n if (err instanceof TimeoutException) return `Too slow: ${err.message}`;\n return err instanceof Error ? (err.stack ?? err.message) : String(err);\n}\n\n\/\/ import.meta.main is true only when this file is run directly, so\n\/\/ the tests can import login() without starting a login.\nif (import.meta.main) {\n try {\n const ok = await login(Bun.argv[2] ?? "https:\/\/example.com\/login");\n console.log(ok ? "logged in" : "NOT logged in");\n process.exit(ok ? 0 : 2);\n } catch (err) {\n console.error(explain(err));\n \/\/ A hung socket would keep Bun alive, so leave explicitly.\n process.exit(1);\n }\n}<\/pre>\n<\/div>\nCommon errors when you solve reCAPTCHA in Bun<\/h2>\n