To solve CAPTCHAs in Browser Use on your own browser, register a custom tool that reads the widget’s sitekey from the page, asks CapSkip for a token and writes it into the form, then tell the agent in its system message that the tool exists. That covers Browser Use CAPTCHA handling on a local Chromium, apart from two limits that both default to 180 seconds and need raising, because a reCAPTCHA solve can run longer than either. The system message part is not optional. Browser Use’s default system prompt tells the model that CAPTCHAs are solved automatically, which is true on Browser Use’s cloud browsers and false on a local Chromium, so without it the agent waits for a solve that never comes. This guide builds the Browser Use CAPTCHA tool step by step, checked against Browser Use 0.13.10.<\/p>\n
# Quoted, so cmd.exe does not read >= as a redirect\npip install browser-use "capskip>=1.3.0"<\/pre>\n<\/div>\nWhy does Browser Use ignore CAPTCHAs on a local browser?<\/h2>\n
Because it has been told to. The browser rules in the system prompt Browser Use uses with its default settings include the line "CAPTCHAs are automatically solved by the browser", followed by an instruction not to try solving them by hand. That describes Browser Use’s cloud browsers, which solve CAPTCHAs in their own proxy and announce it to the library. The library has a matching watchdog, switched on by the captcha_solver setting on BrowserProfile (on by default), which pauses the agent while a cloud browser solves. It listens only for events those cloud browsers send.<\/p>\n
On a Chromium on your own machine no such event ever arrives. The agent sees the widget, believes the rules, and waits, scrolls or tries another route until it runs out of steps. When a run ends that way, Browser Use suggests switching to its cloud browsers. The alternative, if you want the browser on your own hardware, is to give the agent a tool that really solves the widget and to correct the rule it was given.<\/p>\n
Step 1: register a solve_captcha tool<\/h2>\n
Custom tools are async functions registered with the tools.action decorator on a Tools instance. Browser Use injects special parameters by name: browser_session gives you the live session and page_url the address of the current page. The tool needs two small pieces of JavaScript, one to find the widget and one to fill in the token.<\/p>\n
\nFIND = """() => {\n const w = document.querySelector(\n '.g-recaptcha[data-sitekey], .cf-turnstile[data-sitekey]');\n if (!w) return null;\n return {\n kind: w.classList.contains('cf-turnstile') ? 'turnstile' : 'recaptcha',\n sitekey: w.dataset.sitekey,\n invisible: w.dataset.size === 'invisible' || w.tagName !== 'DIV',\n enterprise: !!document.querySelector(\n 'script[src*="recaptcha\/enterprise.js"]'),\n callback: w.dataset.callback || null,\n };\n}"""\n\nFILL = """(kind, token, callback) => {\n const name = kind === 'turnstile' ? 'cf-turnstile-response'\n : 'g-recaptcha-response';\n const fields = document.querySelectorAll(`[name="${name}"]`);\n fields.forEach(f => { f.value = token; });\n if (callback && typeof window[callback] === 'function') {\n window[callback](token);\n }\n return fields.length;\n}"""<\/pre>\n<\/div>\nBoth are written as arrow functions, because the page object’s evaluate method refuses anything else. It passes extra arguments as JSON, and it always returns a string: an object comes back JSON-encoded, a number as its digits, and null as an empty string. FILL writes the token into the response field the widget created and calls the function named in data-callback if the widget declares one, since some forms wait for that callback instead of reading the field.<\/p>\n
FIND also reads two things the solve depends on. A widget bound to a button is invisible even without a data-size attribute, so any g-recaptcha element that is not a div counts as invisible. And a page that loads Google’s enterprise.js script is solved as reCAPTCHA Enterprise, since Enterprise widgets use the same markup as the standard ones.<\/p>\n
\n@tools.action(\n "Solve the reCAPTCHA v2 or Cloudflare Turnstile widget on the current "\n "page. Call it after the other fields are filled, then submit the form "\n "unless the page has already moved on."\n)\nasync def solve_captcha(browser_session: BrowserSession, page_url: str):\n page = await browser_session.must_get_current_page()\n raw = await page.evaluate(FIND)\n widget = json.loads(raw) if raw else None\n if not widget:\n return ActionResult(error="No reCAPTCHA or Turnstile widget found.")\n\n try:\n if widget["kind"] == "turnstile":\n result = await solver.turnstile(widget["sitekey"], page_url)\n else:\n extra = {"invisible": 1} if widget["invisible"] else {}\n result = await solver.recaptcha(\n widget["sitekey"], page_url,\n enterprise=int(widget["enterprise"]), **extra)\n except CapSkipError as exc:\n return ActionResult(error=f"CapSkip did not solve it: {exc!r}")\n\n filled = await page.evaluate(\n FILL, widget["kind"], result["code"], widget["callback"])\n if filled == "0":\n return ActionResult(error="Solved, but no response field to fill.")\n return ActionResult(\n extracted_content=f"Solved the {widget['kind']} CAPTCHA on {page_url} "\n "and filled in the token. Submit the form now, "\n "unless the page has already moved on.",\n )<\/pre>\n<\/div>\nThe description string is what the model reads when it decides which action to take, so it says when to call the tool as well as what it does. The success message goes in extracted_content alone. When an ActionResult also sets long_term_memory, Browser Use shows the model the memory and drops the content, so an instruction such as "Submit the form now" placed in the content never arrives. Every failure comes back as an ActionResult with an error the model can read and react to, rather than an exception.<\/p>\n
Use AsyncCapSkip here, not the synchronous CapSkip client. Browser Use runs the browser connection on the same event loop as your tool, and a blocking solve would freeze all of it for as long as the solve takes. In Python, AsyncCapSkip is a genuine asyncio client rather than an alias.<\/p>\n
Step 2: tell the agent the tool exists<\/h2>\n
Pass the tools to the agent and add one paragraph to its system message. extend_system_message is appended after the default prompt, so it comes after the rule it has to correct.<\/p>\n
\nEXTRA = (\n "This browser does not solve CAPTCHAs on its own, whatever the rules "\n "above say. When a page shows a reCAPTCHA or Turnstile widget, fill in "\n "the other fields, call solve_captcha, then submit the form unless the "\n "page has already moved on. Never click the CAPTCHA checkbox or "\n "challenge yourself."\n)\n\nagent = Agent(\n task="Sign up at https:\/\/example.com\/signup with YOUR_EMAIL.",\n llm=ChatAnthropic(model="claude-opus-5-5", thinking={"type": "adaptive"}),\n tools=tools,\n extend_system_message=EXTRA,\n step_timeout=420,\n)<\/pre>\n<\/div>\nThe order in that paragraph matters. A reCAPTCHA token is only valid for about two minutes, as the guide to reCAPTCHA token expiration<\/a> explains, and each model step takes seconds. Solving first and then filling in a long form can let the token expire before the submit, so the agent is told to solve last. A model can do all three in a single step, typing, solving and clicking submit, and Browser Use runs the actions of a step in order. The clause about the page moving on is for invisible widgets. Their callback usually submits the form itself, so by the time FILL has called it the page has already gone on, and a second click would only fail.<\/p>\n
The thinking argument on ChatAnthropic is not decoration. Browser Use asks Claude for its next action through a tool call, and in version 0.13.10, without thinking, it forces that tool choice. Claude Opus 5.5 and Sonnet 5.5 refuse a forced tool choice with a 400, so the agent would fail every step. With adaptive thinking on, Browser Use lets the model choose the tool, and the request goes through.<\/p>\n
Step 3: raise the two 180 second limits<\/h2>\n
A Browser Use CAPTCHA solve has to fit inside two separate clocks, and both default to 180 seconds.<\/p>\n
\n
- The per-action cap.<\/strong> Every action is wrapped in a timeout read from the BROWSER_USE_ACTION_TIMEOUT_S environment variable, and the agent never passes a value of its own. It is read once, when Browser Use first loads its tools module, which any import of Agent or Tools does, so setting it after that has no effect.<\/li>\n
- The step timeout.<\/strong> Agent’s step_timeout covers a whole step: preparing the page state, the model call, which Browser Use itself allows up to 90 seconds depending on the model, and every action in the step.<\/li>\n<\/ul>\n
On the other side, the SDK polls a reCAPTCHA for up to 300 seconds (recaptchaTimeout), and CapSkip’s own reCAPTCHA settings allow a task up to 250 seconds to wait for a thread and 250 more to solve. Most solves finish far sooner, but a queue or a slow proxy can take one past 180. With both limits at their defaults, the step timeout fires first, because the step started before the action did, and the agent reports that the step timed out after 180 seconds. Raise only step_timeout and the action cap takes over: it cancels the solve mid-poll and reports that the browser may be unresponsive, naming a dead CDP WebSocket. That message is misleading here. The browser is fine; the solve simply outlived the cap. Set both limits above the SDK’s.<\/p>\n
\nimport os\n\n# Before anything imports Agent or Tools from browser_use.\nos.environ.setdefault("BROWSER_USE_ACTION_TIMEOUT_S", "330")\n\nfrom browser_use import Agent # noqa: E402\n\n# Up to 300 s of SDK polling (a few more for the last poll), one\n# model call (90 s for Claude) and the page state, with room to spare.\nagent = Agent(task="...", llm=llm, tools=tools,\n extend_system_message=EXTRA, step_timeout=420)<\/pre>\n<\/div>\nA timed-out step also counts as one of the agent’s consecutive failures, and five in a row stop the agent, so a limit that is too tight costs more than one retry.<\/p>\n
Running CapSkip on a server<\/h2>\n
The tool runs in your Python process, next to the agent. What matters is where that process runs, not where the browser is: even when the session’s cdp_url points at a Chrome on another machine, the solve still travels from your script to CapSkip. While the script and CapSkip share a Windows PC, 127.0.0.1 is right. When the agent moves to a VPS, a CI runner or a scheduled job on another box, loopback points at the wrong machine and the tool returns a NetworkException as its error. Switch CapSkip to Server mode and it listens on your network address or public IP, so the agent can call it over the same API. Use a static public IP when the route crosses the internet, turn on API key validation, and restrict the port with a Windows Firewall rule. The solver stays on your own Windows machine, and solves stay unmetered however many CAPTCHAs the agent meets.<\/p>\n
The SDK does not read environment variables by itself. Read CAPSKIP_HOST, CAPSKIP_PORT and CAPSKIP_API_KEY in your code and pass them to AsyncCapSkip, as the full example does.<\/p>\n
Full working example<\/h2>\n
\n# pip install browser-use "capskip>=1.3.0"\nimport asyncio\nimport json\nimport os\n\n# Browser Use reads this once, when its tools load, so set it first.\nos.environ.setdefault("BROWSER_USE_ACTION_TIMEOUT_S", "330")\n\nfrom browser_use import ActionResult, Agent, BrowserSession, ChatAnthropic, Tools\nfrom capskip import AsyncCapSkip, CapSkipError\n\nsolver = AsyncCapSkip(\n apiKey=os.getenv("CAPSKIP_API_KEY", "capskip"),\n host=os.getenv("CAPSKIP_HOST", "127.0.0.1"),\n port=int(os.getenv("CAPSKIP_PORT", "8080")),\n)\ntools = Tools()\n\nFIND = """() => {\n const w = document.querySelector(\n '.g-recaptcha[data-sitekey], .cf-turnstile[data-sitekey]');\n if (!w) return null;\n return {\n kind: w.classList.contains('cf-turnstile') ? 'turnstile' : 'recaptcha',\n sitekey: w.dataset.sitekey,\n invisible: w.dataset.size === 'invisible' || w.tagName !== 'DIV',\n enterprise: !!document.querySelector(\n 'script[src*="recaptcha\/enterprise.js"]'),\n callback: w.dataset.callback || null,\n };\n}"""\n\nFILL = """(kind, token, callback) => {\n const name = kind === 'turnstile' ? 'cf-turnstile-response'\n : 'g-recaptcha-response';\n const fields = document.querySelectorAll(`[name="${name}"]`);\n fields.forEach(f => { f.value = token; });\n if (callback && typeof window[callback] === 'function') {\n window[callback](token);\n }\n return fields.length;\n}"""\n\n\n@tools.action(\n "Solve the reCAPTCHA v2 or Cloudflare Turnstile widget on the current "\n "page. Call it after the other fields are filled, then submit the form "\n "unless the page has already moved on."\n)\nasync def solve_captcha(browser_session: BrowserSession, page_url: str):\n page = await browser_session.must_get_current_page()\n raw = await page.evaluate(FIND)\n widget = json.loads(raw) if raw else None\n if not widget:\n return ActionResult(error="No reCAPTCHA or Turnstile widget found.")\n try:\n if widget["kind"] == "turnstile":\n result = await solver.turnstile(widget["sitekey"], page_url)\n else:\n extra = {"invisible": 1} if widget["invisible"] else {}\n result = await solver.recaptcha(\n widget["sitekey"], page_url,\n enterprise=int(widget["enterprise"]), **extra)\n except CapSkipError as exc:\n return ActionResult(error=f"CapSkip did not solve it: {exc!r}")\n filled = await page.evaluate(\n FILL, widget["kind"], result["code"], widget["callback"])\n if filled == "0":\n return ActionResult(error="Solved, but no response field to fill.")\n return ActionResult(\n extracted_content=f"Solved the {widget['kind']} CAPTCHA on {page_url} "\n "and filled in the token. Submit the form now, "\n "unless the page has already moved on.",\n )\n\n\nEXTRA = (\n "This browser does not solve CAPTCHAs on its own, whatever the rules "\n "above say. When a page shows a reCAPTCHA or Turnstile widget, fill in "\n "the other fields, call solve_captcha, then submit the form unless the "\n "page has already moved on. Never click the CAPTCHA checkbox or "\n "challenge yourself."\n)\n\n\nasync def main():\n agent = Agent(\n task="Sign up at https:\/\/example.com\/signup with YOUR_EMAIL, "\n "then report what the page says.",\n # Adaptive thinking lets Browser Use leave the tool choice to Claude.\n llm=ChatAnthropic(model="claude-opus-5-5", thinking={"type": "adaptive"}),\n tools=tools,\n extend_system_message=EXTRA,\n step_timeout=420,\n )\n history = await agent.run(max_steps=25)\n print(history.final_result())\n\n\nasyncio.run(main())<\/pre>\n<\/div>\nWe ran this loop end to end against test pages for a checkbox widget, an invisible widget bound to a button, an Enterprise page and a Turnstile widget, with a scripted stand-in for the model so each step was predictable. The prompt arrives with the extra paragraph after the default rules, solve_captcha appears among the actions the model can choose, the token lands in the form, the data-callback function fires, the tool’s instruction reaches the model, and the submit is accepted. We also captured the request ChatAnthropic sends, to confirm that adaptive thinking leaves the tool choice to the model. With a real model the only difference is that the model decides when to call the tool, which is what the description and the extra paragraph are for. The raw endpoints behind both methods are documented in the API reference<\/a>.<\/p>\n
Common errors and what they mean<\/h2>\n