Browser Runtimes

CAPTCHA

View as Markdown

BCTRL can help browser runtimes handle supported CAPTCHA challenges during automation. Configure CAPTCHA behavior at runtime launch, then continue using your native browser framework over CDP.

Enable CAPTCHA solving

CAPTCHA auto-solving defaults to false.

1const runtime = await space.runtimes.browser.launch({
2  name: "signup-flow",
3  config: {
4    captcha: {
5      autoSolve: true,
6    },
7  },
8});

Then connect normally.

1const connection = await runtime.connections.create({
2  protocol: "cdp",
3});

If you are controlling the runtime through CDP, either enable captcha.autoSolve before creating the runtime or release the connection before starting a manual CAPTCHA invocation.

Manual solve invocation

1const invocation = await runtime.invocations.create({
2  provider: "bctrl",
3  method: "solveCaptcha",
4  target: {
5    type: "browser_page",
6    page: "active",
7  },
8  input: {
9    timeoutMs: 60_000,
10  },
11});

Supported challenge families

Support can include common challenge types such as reCAPTCHA, hCaptcha, Cloudflare Turnstile, GeeTest, Arkose, and DataDome, depending on site behavior and solver availability.

Observability

CAPTCHA attempts appear in run events when BCTRL can observe them. Use run events and artifacts to debug whether a challenge was detected, solved, skipped, or failed.

1const run = await runtime.currentRun();
2
3const { events } = await run.events.list({
4  kind: ["captcha"],
5});