CloakBrowser

Stealth Chromium that passes every bot detection test.

Drop-in Playwright/Puppeteer replacement. Same API — just swap the import. Scores 0.9 on reCAPTCHA v3, passes Cloudflare Turnstile, and clears 30/30 stealth detection tests.

• 🔒 25 source-level C++ patches — not JS injection, not config flags
• 🎯 0.9 reCAPTCHA v3 score — human-level, server-verified
• ☁️ Passes Cloudflare Turnstile, FingerprintJS, BrowserScan — 30/30 tests
• 🔄 Drop-in replacement — works with both Playwright and Puppeteer
• 📦 npm install cloakbrowser — binary auto-downloads, zero config

Install

# With Playwright
npm install cloakbrowser playwright-core

# With Puppeteer
npm install cloakbrowser puppeteer-core

On first launch, the stealth Chromium binary auto-downloads (200MB, cached at `/.cloakbrowser/`).

Usage

Playwright (default)

import { launch } from 'cloakbrowser';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://protected-site.com');
console.log(await page.title());
await browser.close();

Puppeteer

Note: Playwright is recommended for sites with reCAPTCHA Enterprise. Puppeteer's CDP protocol leaks automation signals that reCAPTCHA Enterprise can detect. This is a known Puppeteer limitation, not specific to CloakBrowser.

import { launch } from 'cloakbrowser/puppeteer';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://protected-site.com');
console.log(await page.title());
await browser.close();

Options

import { launch, launchContext } from 'cloakbrowser';

// With proxy
const browser = await launch({
  proxy: 'http://user:pass@proxy:8080',
});

// Headed mode (visible browser window)
const browser = await launch({ headless: false });

// Extra Chrome args
const browser = await launch({
  args: ['--window-size=1920,1080'],
});

// With timezone and locale (sets --fingerprint-timezone and --lang binary flags)
const browser = await launch({
  timezone: 'America/New_York',
  locale: 'en-US',
});

// Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib)
const browser = await launch({
  proxy: 'http://proxy:8080',
  geoip: true,
});

// Browser + context in one call (timezone/locale set both binary flags AND context)
const context = await launchContext({
  userAgent: 'Custom UA',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US',
  timezoneId: 'America/New_York',
});

Auto Timezone/Locale from Proxy IP

When using a proxy, antibot systems check that your browser's timezone and locale match the proxy's location. Install mmdb-lib to enable auto-detection from an offline GeoIP database (~70 MB, downloaded on first use):

npm install mmdb-lib

// Auto-detect — timezone and locale set from proxy's IP geolocation
const browser = await launch({ proxy: 'http://proxy:8080', geoip: true });

// Works with launchContext too
const context = await launchContext({ proxy: 'http://proxy:8080', geoip: true });

// Explicit values always win over auto-detection
const browser = await launch({ proxy: 'http://proxy:8080', geoip: true, timezone: 'Europe/London' });

Note: For rotating residential proxies, the DNS-resolved IP may differ from the exit IP. Pass explicit timezone/locale in those cases.

Utilities

import { ensureBinary, clearCache, binaryInfo, checkForUpdate } from 'cloakbrowser';

// Pre-download binary (e.g., during Docker build)
await ensureBinary();

// Check installation
console.log(binaryInfo());

// Force re-download
clearCache();

// Manually check for newer Chromium version
const newVersion = await checkForUpdate();
if (newVersion) console.log(`Updated to ${newVersion}`);

Test Results

Configuration

Migrate From Playwright

- import { chromium } from 'playwright';
- const browser = await chromium.launch();
+ import { launch } from 'cloakbrowser';
+ const browser = await launch();

const page = await browser.newPage();
// ... rest of your code works unchanged

Platforms

On Windows? You can still use CloakBrowser via Docker or with your own Chromium binary by setting CLOAKBROWSER_BINARY_PATH=/path/to/chrome.

Requirements

• Node.js >= 18
• One of: playwright-core >= 1.40 or puppeteer-core >= 21

Troubleshooting

reCAPTCHA v3 scores are low (0.1–0.3)

Avoid page.waitForTimeout() — it sends CDP protocol commands that reCAPTCHA detects. Use native sleep instead:

// Bad — sends CDP commands, reCAPTCHA detects this
await page.waitForTimeout(3000);

// Good — invisible to the browser
await new Promise(r => setTimeout(r, 3000));

Other tips for maximizing reCAPTCHA scores:

• Use Playwright, not Puppeteer — Puppeteer sends more CDP protocol traffic that reCAPTCHA detects (details)
• Use residential proxies — datacenter IPs are flagged by IP reputation, not browser fingerprint
• Spend 15+ seconds on the page before triggering reCAPTCHA — short visits score lower
• Space out requests — back-to-back grecaptcha.execute() calls from the same session get penalized. Wait 30+ seconds between pages with reCAPTCHA
• Use a fixed fingerprint seed (--fingerprint=12345) for consistent device identity across sessions
• Minimize page.evaluate() calls before the reCAPTCHA check fires — each one sends CDP traffic

Links

• 🌐 Website
• 🐛 Bug reports & feature requests
• 📦 PyPI (Python package)
• 📖 Full documentation
• 📧 Contact: cloakhq@pm.me

License

MIT — see LICENSE.