cloak-real-browser

A stealth browser automation package using CloakBrowser with Puppeteer. Bypass bot detection with C++ level fingerprint patches.

Note: This package uses Puppeteer with chrome-launcher for natural browser initialization, similar to puppeteer-real-browser.

Features

• 🛡️ 33 C++ Level Patches - Canvas, WebGL, audio, fonts, GPU, screen, automation signals, input behavior
• 🤖 Human-like Behavior - Natural mouse curves, keyboard timing, scroll patterns
• ✅ Passes Major Detectors - Cloudflare Turnstile, FingerprintJS, BrowserScan
• 🎯 0.9 reCAPTCHA v3 Score - Human-level, server-verified
• 🔧 Drop-in Replacement - Works with existing Puppeteer code
• 🆓 Free & Open Source - No subscriptions or usage limits
• 📦 Dual Module Support - Works with both CommonJS (CJS) and ECMAScript Modules (ESM)

Installation

npm install cloak-real-browser

Linux Requirements

sudo apt-get install xvfb  # for headless operation

Quick Start

CommonJS (CJS)

const { connect } = require('cloak-real-browser');

async function main() {
  const { page, browser } = await connect({
    headless: false,
    humanize: true,
  });

  await page.goto('https://example.com');
  await browser.close();
}

main();

ES Modules (ESM)

import { connect } from 'cloak-real-browser';

async function main() {
  const { page, browser } = await connect({
    headless: false,
    humanize: true,
  });

  await page.goto('https://example.com');
  await browser.close();
}

main();

Using puppeteer subpath export

import { connect } from 'cloak-real-browser/puppeteer';

const { page, browser } = await connect();
await page.goto('https://example.com');

API

connect(options)

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | headless | boolean\|string | false | Headless mode (false, true, "new", "shell") | | args | string[] | [] | CloakBrowser launch arguments | | customConfig | object | {} | Custom configuration (userDataDir, chromePath, etc.) | | humanize | boolean | true | Enable human-like behavior | | humanConfig | object | {} | Human behavior configuration | | proxy | string | undefined | Proxy URL (e.g., "http://user:pass@proxy:8080") | | timezone | string | undefined | Timezone (e.g., "America/New_York") | | locale | string | undefined | Locale (e.g., "en-US") | | turnstile | boolean | true | Auto-click Cloudflare Turnstile captchas | | connectOption | object | {} | Puppeteer connect options | | plugins | array | [] | Puppeteer extra plugins | | disableXvfb | boolean | false | Disable Xvfb on Linux | | ignoreAllFlags | boolean | false | Ignore all default flags |

Returns

{ page, browser, chrome }

• page: Puppeteer Page object with extended methods
• browser: Puppeteer Browser object
• chrome: Chrome launcher instance with port and process info

Extended Page Methods

The package adds human-like interaction methods to the page object:

page.realCursor(x, y, options)

Natural mouse movement with bezier curves.

await page.realCursor(500, 300, { steps: 10, delay: 10 });

page.realClick(selector, options)

Human-like click with natural mouse movement.

await page.realClick('#submit-button', {
  delay: 100,
  waitForNavigation: true
});

page.realType(selector, text, options)

Human-like typing with random delays and mistype corrections.

await page.realType('#username', '[email protected]', {
  delay: 100,
  mistypeChance: 0.02
});

page.realScroll(amount, options)

Natural scroll with easing.

await page.realScroll(500, { duration: 1000, steps: 20 });

page.randomScroll(options)

Random scroll for natural browsing behavior.

await page.randomScroll({
  minScroll: 100,
  maxScroll: 500,
  pauseBetween: true
});

Usage Examples

Full Configuration (CJS)

const { connect } = require('cloak-real-browser');

async function test() {
  const { page, browser } = await connect({
    headless: false,
    args: ['--start-maximized'],
    humanize: true,
    humanConfig: {
      mistype_chance: 0.05,
      typing_delay: 100,
      idle_between_actions: true,
    },
    proxy: 'http://user:pass@proxy:8080',
    timezone: 'America/New_York',
    locale: 'en-US',
    turnstile: true,
    connectOption: { defaultViewport: null },
  });

  await page.goto('https://protected-site.com');
  await browser.close();
}

test();

Full Configuration (ESM)

import { connect } from 'cloak-real-browser';

async function test() {
  const { page, browser } = await connect({
    headless: false,
    args: ['--start-maximized'],
    humanize: true,
    humanConfig: {
      mistype_chance: 0.05,
      typing_delay: 100,
      idle_between_actions: true,
    },
    proxy: 'http://user:pass@proxy:8080',
    timezone: 'America/New_York',
    locale: 'en-US',
    turnstile: true,
    connectOption: { defaultViewport: null },
  });

  await page.goto('https://protected-site.com');
  await browser.close();
}

test();

Persistent Profile

const { connect } = require('cloak-real-browser');

async function main() {
  const { page, browser } = await connect({
    customConfig: {
      userDataDir: './my-profile',
    },
  });

  // Cookies and localStorage persist across sessions
  await page.goto('https://example.com');
  await browser.close();
}

main();

With Puppeteer Extra Plugins

npm install puppeteer-extra puppeteer-extra-plugin-click-and-wait

const { connect } = require('cloak-real-browser');
const clickAndWaitPlugin = require('puppeteer-extra-plugin-click-and-wait')();

async function main() {
  const { page, browser } = await connect({
    plugins: [clickAndWaitPlugin],
  });

  await page.goto('https://google.com', { waitUntil: 'domcontentloaded' });
  await page.clickAndWaitForNavigation('body');
  await browser.close();
}

main();

Human-like Form Automation

const { connect } = require('cloak-real-browser');

async function fillForm() {
  const { page, browser } = await connect({ humanize: true });

  await page.goto('https://example.com/register');

  // Natural typing with mistypes
  await page.realType('#email', '[email protected]');
  await page.realType('#password', 'securepassword123');

  // Random scroll before submitting
  await page.randomScroll();

  // Natural click
  await page.realClick('#submit', { waitForNavigation: true });

  await browser.close();
}

fillForm();

Auto-detect Timezone from Proxy

const { connect } = require('cloak-real-browser');

async function main() {
  const { page, browser } = await connect({
    proxy: 'http://proxy:8080',
    // CloakBrowser auto-detects timezone/locale from proxy IP
  });

  await page.goto('https://example.com');
  await browser.close();
}

main();

Fingerprint Management

Default Behavior

Auto-generates random fingerprint seed at startup.

Persistent Identity

const { connect } = require('cloak-real-browser');

async function main() {
  const { page, browser } = await connect({
    args: ['--fingerprint=12345'],
  });

  await page.goto('https://example.com');
  await browser.close();
}

main();

Custom Fingerprint Flags

const { connect } = require('cloak-real-browser');

async function main() {
  const { page, browser } = await connect({
    args: [
      '--fingerprint=12345',
      '--fingerprint-platform=windows',
      '--fingerprint-gpu-vendor=NVIDIA',
      '--fingerprint-gpu-renderer=GeForce RTX 3080',
      '--fingerprint-storage-quota=5000',
    ],
  });

  await page.goto('https://example.com');
  await browser.close();
}

main();

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CLOAKBROWSER_BINARY_PATH | — | Skip download, use local binary | | CLOAKBROWSER_CACHE_DIR | ~/.cloakbrowser | Binary cache directory | | CLOAKBROWSER_DOWNLOAD_URL | cloakbrowser.dev | Custom download URL | | CLOAKBROWSER_AUTO_UPDATE | true | Disable background updates | | CLOAKBROWSER_SKIP_CHECKSUM | false | Skip SHA-256 verification |

Test Results (Mar 2026, Chromium 145)

| Detection Service | Stock Puppeteer | cloak-real-browser | |-------------------|-----------------|--------------------| | reCAPTCHA v3 | 0.1 (bot) | 0.9 (human) | | Cloudflare Turnstile | FAIL | PASS | | FingerprintJS | DETECTED | PASS | | BrowserScan | DETECTED | NORMAL (4/4) | | navigator.webdriver | true | false |

Troubleshooting

Chrome Not Found

Set custom Chrome path:

const { connect } = require('cloak-real-browser');

const { page } = await connect({
  customConfig: {
    chromePath: 'C:\\Program Files\\CloakBrowser\\cloak.exe',
  },
});

ECONNREFUSED Errors (Windows)

1. Kill existing Chrome: taskkill /f /im chrome.exe
2. Check hosts file: 127.0.0.1 localhost
3. Run as Administrator

Linux Display Issues

sudo apt-get install xvfb

Or disable xvfb:

const { connect } = require('cloak-real-browser');

const { page } = await connect({
  disableXvfb: true,
});

Testing

The package includes test files for both module systems:

Run CJS Tests

npm test
# or
node test/test-cjs.js

Run ESM Tests

npm run test:esm
# or
node test/test-esm.js

Test Files

• test/test-cjs.js - CommonJS tests using require()
• test/test-esm.js - ESM tests using import

Comparison with Similar Packages

| Feature | cloak-real-browser | puppeteer-real-browser | brave-real-browser | |---------|--------------------|------------------------|--------------------| | C++ Level Patches | ✅ 33 patches | ❌ JS injection only | ❌ JS injection only | | Human-like Behavior | ✅ Built-in | ⚠️ External plugin | ⚠️ External plugin | | Auto Turnstile Click | ✅ Built-in | ✅ Built-in | ✅ Built-in | | Persistent Profiles | ✅ | ✅ | ✅ | | Free & Open Source | ✅ | ⚠️ No longer updated | ✅ | | Puppeteer (No CDP leaks) | ✅ | ✅ | ✅ |

Disclaimer

This software is for educational and informational purposes only. Not intended to bypass security measures for malicious purposes. Use at your own risk and ensure compliance with target websites' terms of service.

License

MIT

Credits

• Author: frxldi-xyz
• CloakBrowser - Stealth Chromium browser with C++ patches
• puppeteer-real-browser - Inspiration for this package