BotBrowser: What It Is, How To Set It Up, and Why It Matters for Fingerprint Defense

TL;DR

• BotBrowser is a Chromium-based privacy browser core that enforces consistent fingerprint signals across Windows, macOS, and Linux using a single profile file. 
• Browser fingerprinting enables tracking across sessions and devices without cookies; most antidetect tools rely on JavaScript-level overrides that can still diverge across operating systems, while BotBrowser applies fingerprint control at the Chromium engine level. 
• You can install BotBrowser via the launcher and clone the free demo profiles from GitHub.
• Launch BotBrowser via the CLI for manual sessions, before connecting Playwright to it over the Chrome DevTools Protocol (CDP) via JavaScript so it can be driven programmatically.
• Fingerprint consistency should be validated with tools such as CreepJS, Pixelscan, and Iphey and confirmed by relaunching the same profile and comparing outputs.

What is BotBrowser?

BotBrowser is a privacy-focused browser core built to protect against browser fingerprinting and enable consistent browser identities across different operating systems. Rather than relying on extension-based spoofing or wrapper-level patches, it controls fingerprint signals directly within a Chromium-based browser runtime.

The engine is developed in-house on top of Chromium, without depending on Chromium forks or third-party antidetect projects. While the core browser engine remains proprietary, supporting components such as the launcher, profiles, and related tooling are available under the MIT license.

At the center of BotBrowser's architecture are encrypted profile files that define a browser identity. A profile contains attributes such as user agent data, screen characteristics, fonts, device APIs, rendering behavior, and touch capabilities. The same profile can be run on Windows, macOS, or Linux while maintaining a consistent browser fingerprint across platforms.

BotBrowser supports multiple browser and platform identities, including Chrome, Edge, Brave, Opera, Android, Android WebView, and selected WebKit-family profiles. It also provides advanced controls for network behavior, WebRTC, canvas, WebGL, fonts, timing, and other fingerprinting surfaces.

The project is intended for privacy research, browser fingerprinting analysis, cross-platform consistency testing, and authorized defensive benchmarking. Users should review the Responsible Use Guidelines and Legal Disclaimer before testing against systems they don’t own or have explicit permission to evaluate.

Feature availability varies by subscription tier. Free profiles provide access to core functionality, while PRO and Enterprise plans unlock capabilities such as Android emulation, per-context fingerprints, advanced network controls, and UDP-over-SOCKS5 tunneling.

BotBrowser is often categorized as an antidetect browser. However, it distinguishes itself through its browser-level implementation, profile portability across operating systems, and emphasis on fingerprint consistency rather than profile generation alone. It supports both graphical and headless execution modes while maintaining the same fingerprint behavior across environments. See what a headless browser is to learn more about headless execution. 

Why use BotBrowser instead of traditional browsers or antidetect tools?

Traditional browsers expose hundreds of fingerprinting signals by default, allowing websites to build a unique profile of a device based on its hardware, software, network characteristics, and browser behavior. While many antidetect browsers attempt to mask or modify these signals, most generate operating-system-specific fingerprints that vary between Windows, macOS, and Linux.

BotBrowser takes a different approach. Its profile system is designed to maintain a consistent browser identity across platforms, ensuring the same profile produces the same fingerprint regardless of the underlying operating system. This reduces cross-platform inconsistencies, making fingerprint spoofing easier to detect.

Performance is another area where BotBrowser differs from many fingerprint-modification tools. Because fingerprint protections are implemented within the browser engine itself rather than through JavaScript injection or extension-based patches, BotBrowser operates with performance characteristics that closely resemble a standard Chromium browser. This avoids much of the overhead, compatibility risk, and detectable behavior often associated with runtime spoofing techniques such as undetected_chromedriver or nodriver.

Some of BotBrowser's key technical advantages include:

Cross-platform fingerprint protection 

A single encrypted profile maintains the same browser identity across Windows, macOS, and Linux. User-agent data, rendering characteristics, device APIs, fonts, screen properties, and other fingerprinting surfaces remain aligned regardless of the host operating system.

Network-layer privacy controls 

BotBrowser supports advanced proxy configurations, including SOCKS5-based transport options, WebRTC leak protection, DNS privacy controls, and network-stack behavior designed to minimize exposure of location and connectivity metadata.

Per-context fingerprints 

Enterprise configurations can run multiple isolated fingerprint identities within a single browser process. This enables rapid switching between contexts while reducing the resource overhead typically associated with launching separate browser instances.

Engine-level fingerprint protection 

Fingerprint defenses are implemented directly within the browser engine rather than through injected JavaScript. Protections extend across multiple fingerprinting surfaces, including Canvas, WebGL, WebGPU, AudioContext, text rendering, ClientRects, and other high-entropy APIs. Because the modifications occur below the webpage layer, they are generally more difficult to identify than traditional script-based spoofing approaches.

Automation-ready architecture 

BotBrowser integrates with automation frameworks such as Playwright and Puppeteer while minimizing browser automation signals that websites commonly use to detect bots. This allows automated workflows to operate with a browser environment that more closely resembles a standard user session.

For organizations conducting privacy research, browser fingerprint testing, or authorized defensive evaluations, BotBrowser offers a browser-level approach that prioritizes fingerprint consistency, performance, and cross-platform portability over the patchwork modifications commonly found in traditional antidetect solutions.

Cross-platform fingerprint protection: How BotBrowser works 

BotBrowser's fingerprinting model is built around encrypted profile files (.enc). Each profile contains a complete browser identity, including attributes such as the user agent, screen resolution, device memory, hardware concurrency, touch capabilities, installed fonts, GPU characteristics, and other fingerprintable signals.

When a profile is launched, these values are applied directly within the Chromium engine rather than through browser extensions or JavaScript-based spoofing. As a result, websites interact with the profile-defined identity rather than with the host machine's actual hardware and operating system characteristics.

Consistent rendering across operating systems 

Fonts are among the most commonly used browser fingerprinting signals because font availability and text rendering vary significantly between operating systems. To address this, BotBrowser includes embedded font bundles that replicate the font environments of Windows, macOS, Linux, and Android.

This allows font enumeration checks, text measurements, and rendering tests to produce results consistent with the selected profile rather than the underlying operating system. A profile configured to resemble Windows, for example, can maintain Windows-style font behavior even when running on Linux or macOS.

Graphics and media fingerprint stability 

Modern fingerprinting systems frequently rely on graphics and media APIs such as Canvas, WebGL, WebGPU, and AudioContext. These APIs often reveal subtle differences in hardware, drivers, and operating systems.

BotBrowser applies deterministic profile-based noise across these surfaces, ensuring that outputs remain stable for a given profile while still differing naturally between separate profiles. This helps preserve fingerprint consistency without exposing the host machine's real rendering characteristics.

Network and location alignment

Fingerprint consistency extends beyond browser APIs to the network layer. BotBrowser can align timezone, locale, language preferences, and related regional settings with the configured proxy’s geographical location, reducing discrepancies that detection systems often flag as suspicious.

Additional protections help prevent network-level information leaks, including controls for WebRTC SDP and ICE candidate exposure, DNS privacy mechanisms, and Client Hints synchronization. Signals such as device memory, viewport characteristics, DPR values, and User-Agent Client Hints remain consistent with the active profile identity.

The platform also aims to maintain consistency across lower-level network characteristics, including TLS and JA3 fingerprint behavior, helping ensure that browser, network, and transport-layer signals present a coherent identity.

Platform and browser emulation

BotBrowser supports multiple browser identities –  including Chrome, Edge, Brave, and Opera –  and provides Android and Android WebView emulation capabilities. Browser-specific behaviors, network protocols, and HTTP implementation details are designed to remain aligned with the selected profile configuration.

Timing and behavioral defenses

Advanced fingerprinting systems increasingly rely on timing analysis rather than static browser attributes alone. To reduce the effectiveness of these techniques, BotBrowser introduces controlled timing protections across a range of browser operations.

Additional safeguards target stack-trace and execution-environment fingerprints across the main thread, Web Workers, and WebAssembly contexts. These protections help limit the amount of information that can be inferred through performance measurements, execution characteristics, and runtime behavior.

Taken together, these layers protect both traditional fingerprinting surfaces – such as fonts, graphics, and browser APIs – and the more subtle timing and behavioral signals used by modern detection systems.

Getting started with BotBrowser

Prerequisites

Install these first:

• Download Node.js (v18 or later) from nodejs.org. Verify that it works by running node --version and npm --version on the command terminal.
• Download Git from git-scm.com on Windows, or run brew install git on macOS.

Step 1: Install BotBrowser

On Windows, run this in PowerShell (as administrator):

irm https://raw.githubusercontent.com/botswin/BotBrowser/main/launcher/scripts/setup-windows.ps1 -OutFile $env:TEMP\setup.ps1; powershell -ExecutionPolicy Bypass -File $env:TEMP\setup.ps1

On macOS, download the launcher package for your architecture from the GitHub releases page and run the installer.

The installer downloads the launcher and a versioned Chromium kernel. Keep in mind that BotBrowser doesn't install to a single fixed path. On Windows, the kernel is installed into your user profile's AppData folder, not in C:\Program Files. Find the exact kernel path by running this in PowerShell:

Get-ChildItem "$env:APPDATA\BotBrowser\kernels" -Recurse -Filter chrome.exe

This returns a path that looks like:

C:\Users\your-username\AppData\Roaming\BotBrowser\kernels\kernel-version\Chrome-bin\chrome.exe

On macOS, the kernel is typically located in ~/Library/Application Support/BotBrowser/kernels/. The executable in this directory is named BotBrowser rather than chrome.exe. 

Step 2: Get a profile

Clone the BotBrowser repository to access the free demo profiles:

git clone https://github.com/botswin/BotBrowser.git C:\BotBrowser\repo

This will clone the repository to BotBrowser/repo on your local machine. Profiles are stored in the profiles/stable/ directory inside the cloned repository. You should select a profile that matches your kernel’s major version – for example, a kernel version 149 would pair with chrome149_win11_x64.enc.

Note: Free demo profiles may be restricted by a “Premium profile required” limitation, which can block certain automation features, including the CDP connection used by Playwright. These profiles still support manual browsing and basic CLI launches, but full automation workflows (covered in the next section) require a PRO or Enterprise profile.

Step 3: Launch BotBrowser via CLI

On Windows, open Command Prompt (CMD) and run this command:

"C:\Users\Your-User\AppData\...\Chrome-bin\chrome.exe" ^
--bot-profile="C:\BotBrowser\repo\profiles\stable\your-file-version.enc" ^
--user-data-dir="%TEMP%\botprofile_%RANDOM%"

Here’s the macOS equivalent:

"~/Library/Application Support/BotBrowser/kernels/" \
--bot-profile="/path/to/your/.enc file/" \
--user-data-dir="/tmp/botprofile_$RANDOM"

To route traffic through a proxy, add the --proxy-server flag:

"C:\Users\Your-User\AppData\...\Chrome-bin\chrome.exe" ^
--bot-profile="C:\BotBrowser\repo\profiles\stable\chrome149_win11_x64.enc" ^
--user-data-dir="%TEMP%\botprofile_%RANDOM%" ^
--proxy-server="socks5://user:password@127.0.0.1:8989" 

Three flags are critical in this setup: --bot-profile defines the fingerprint identity, --user-data-dir isolates session state, and --proxy-server controls network routing. Always generate a new --user-data-dir for each session. Reusing the same directory across launches can lead to profile contamination and inconsistent fingerprint behavior.

Timezone, locale, and language are automatically inferred from the proxy IP by default, so manual configuration is usually unnecessary unless you're intentionally testing edge cases.

Step 4: Connect Playwright through CDP

This is where BotBrowser’s automation model differs from standard Playwright workflows. Instead of Playwright launching and managing the browser process, BotBrowser starts first and exposes a Chrome DevTools Protocol (CDP) endpoint. Playwright then attaches to this running instance rather than spawning its own browser.

In practice, launching BotBrowser directly via launchPersistentContext() can lead to unstable sessions and intermittent “target closed” errors, particularly when using profiles without full automation permissions. The more reliable approach is to start BotBrowser independently and later connect to it over CDP.

Run the following commands one after the other to create a new Node.js project and install Playwright:

mkdir botbrowser-test
cd botbrowser-test
npm init -y
npm install playwright

Launch BotBrowser with the remote debugging port enabled. On Windows:

"C:\Users\Your-User\AppData\...\Chrome-bin\chrome.exe" ^
--bot-profile="C:\BotBrowser\repo\profiles\stable\your-file-version.enc" ^
--remote-debugging-port=9222 ^
--user-data-dir="%TEMP%\botprofile_%RANDOM%"

On macOS:

"~/Library/Application Support/BotBrowser/kernels/" \
--bot-profile="/path/to/your/.enc file/" \
--remote-debugging-port=9222 \
--user-data-dir="/tmp/botprofile_$RANDOM"

Before writing any automation code, verify that the CDP endpoint is reachable by opening http://127.0.0.1:9222/json/version in a browser. A working setup will return a JSON response containing fields such as webSocketDebuggerUrl with basic browser metadata. 

If the endpoint doesn’t respond, it typically means the debugging port hasn't been initialized. In most cases, this is related to the profile tier rather than a scripting issue, so confirm automation support before debugging the integration.

Once the endpoint responds, create a new file test.js in botbrowser-test and paste in the following code:

const { chromium } = require('playwright');

(async () => {
  // Connect to the BotBrowser instance that's already running.
  // BotBrowser must be launched first with --remote-debugging-port=9222.
  const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');

  // Reuse the existing context rather than creating a new one.
  const context = browser.contexts()[0];
  const page = context.pages()[0] || await context.newPage();

  // Strip Playwright-specific artifacts so they don't leak into the fingerprint.
  await page.addInitScript(() => {
    delete window.__playwright__binding__;
    delete window.__pwInitScripts;
  });

  await page.goto('https://abrahamjuliot.github.io/creepjs/');
  await page.waitForTimeout(15000);

  // Disconnects Playwright without closing the BotBrowser instance.
  await browser.close();
})();

Run it with node test.js. The script should reuse the existing BotBrowser tab, navigate to the fingerprint test page, and disconnect cleanly.

Here are some configuration tips for more reliability:

• Always set the proxy through --proxy-server at launch, not through framework-level options like page.authenticate(). The latter disables BotBrowser's IP-based geo-detection.
• Besides Playwright, BotBrowser also supports Puppeteer and a framework-less --bot-script approach that connects directly over CDP, with fewer injected artifacts.

A few additional tips on session control:

• --bot-cookies can accept either inline JSON or a file path, allowing cookies to be preloaded into a session before launch.
• Bookmark and history injection can also be used to make a session appear more naturally aged and consistent over time.
• Per-context fingerprints (available on PRO and Enterprise tiers) enable multiple isolated identities within a single browser process, reducing the need to spawn separate instances.

For broader Playwright patterns beyond this setup, see the Playwright web scraping tutorial. If you’re comparing automation frameworks, our Puppeteer vs. Playwright guide breaks down the key trade-offs. BotBrowser also supports Docker-based deployment for containerized environments, and standard cookie handling can be used for session persistence.

For best results in geo-targeted workflows, you can pair BotBrowser with our residential proxies to align fingerprint and network signals. In scenarios requiring frequent IP rotation, our rotating proxies can be layered on top of the same profile-based setup.

Validating BotBrowser's fingerprint protection across platforms and tracking systems

Manual validation

Manual validation is the simplest way to verify that a BotBrowser profile is working as expected, and it can be performed using free demo profiles.

After launching BotBrowser from the command line, visit one or more fingerprint testing sites:

• CreepJS provides the most detailed fingerprint analysis. Pay particular attention to the trust score and fingerprint hash, and verify that they remain consistent across launches.
• Pixelscan is useful for validating fingerprint consistency and identifying potential anomalies.
• Iphey offers an additional point of comparison and can help surface mismatched or suspicious signals.

During the initial run, record key fingerprint attributes such as the user agent, WebGL renderer, timezone, language settings, canvas fingerprint, and overall trust score.

Next, close the browser, relaunch it using the same profile, and repeat the tests. A correctly configured profile should produce the same fingerprint characteristics across both sessions. Significant changes between launches may indicate a profile mismatch, configuration issue, or session contamination.

Automated validation

For more comprehensive testing, BotBrowser includes a built-in validation suite that covers over 30 tracking and anti-bot scenarios. These tests target a range of fingerprinting, bot-detection, and challenge systems, including Cloudflare Turnstile, DataDome, PerimeterX, FingerprintJS Pro, hCaptcha, Imperva, Kasada, Shape, reCAPTCHA, ThreatMetrix, and Adscore. The test framework allows individual scenarios to be executed independently, making it easier to validate specific protections or troubleshoot particular detection vectors.

If you have access to multiple environments, two additional validation exercises are particularly valuable:

• Cross-platform testing: Run the same profile on Windows, macOS, and Linux to verify that fingerprint outputs remain consistent across host operating systems.
• Headless vs. GUI testing: Compare fingerprint results between headless and graphical sessions to confirm that both execution modes produce the same browser identity.

Diagnostic tools

BotBrowser includes a few specialized tools for deeper fingerprint inspection:

• CanvasLab records and compares Canvas 2D, WebGL, and WebGL2 output across runs.
• AudioLab records Web Audio API output to verify audio fingerprint consistency.
• Mirror runs distributed validation across multiple browser instances simultaneously, useful for checking privacy posture at scale.

For deeper context on specific anti-bot systems, see our guides on how to bypass CreepJS, how to bypass PerimeterX, and Cloudflare Turnstile. Our CAPTCHA bypass guide covers a broader context for that category of challenge. For targets where fingerprint protection alone isn't enough to get through, Site Unblocker is worth pairing with as a complementary solution. 

Best practices and common pitfalls

Proxy configuration

Configure proxies through --proxy-server or BotBrowser's per-context proxy settings rather than framework-level methods such as page.authenticate(). Browser-level proxy configuration allows BotBrowser to align network and fingerprint signals correctly, while framework-level authentication can interfere with geo-detection and introduce inconsistencies.

When possible, use residential proxies for sessions that require strong location realism. A well-configured browser fingerprint can still appear suspicious if paired with a datacenter IP that doesn't match the profile's geographic characteristics. For maximum network-layer consistency, including support for protocols such as QUIC and STUN, consider using SOCKS5 with UDP tunneling.

Profile management

Treat each session as an isolated environment. Always generate a unique --user-data-dir for every launch to prevent state leakage and profile contamination between runs.

Profile attributes should also align with the proxy location whenever possible. For example, a profile configured for a U.S. user should generally be paired with a U.S.-based proxy. While intentional mismatches can be useful for testing edge cases, they often create inconsistencies that detection systems can flag.

Finally, rotate profiles periodically. Although a profile's fingerprint remains stable by design, long-running identities can accumulate behavioral history over time, making periodic refreshes a sensible operational practice.

Automation hygiene

Even in a hardened browser environment, automation frameworks can introduce detectable artifacts of their own. When using Playwright or Puppeteer, remove framework-specific globals such as __playwright__binding__ and __pwInitScripts through initialization scripts before page code executes.

For workflows that prioritize minimal exposure to automations, the framework-less --bot-script approach can be advantageous because it hooks into the browser earlier in the page lifecycle and leaves behind fewer automation indicators than a traditional framework.

Behavior matters as much as fingerprints. Avoid executing actions with perfectly uniform timing, and introduce realistic delays where appropriate. Many modern anti-bot systems analyze interaction patterns in addition to browser fingerprints, making human-like session behavior an important part of an overall stealth strategy.

Maintenance

Keep BotBrowser and its profiles updated in line with Chromium’s stable release cycle. An outdated browser version can itself become a detectable fingerprint signal if it diverges from commonly observed versions. After each update, confirm that your profiles remain compatible, since new releases ship alongside matching profile sets.

For network setup, rotating proxies help maintain IP diversity across sessions, while residential proxies typically provide a more realistic network footprint than datacenter IPs, especially for geo-sensitive environments.

Final thoughts

BotBrowser is a privacy-focused Chromium core built on a simple principle: a single profile should produce a consistent fingerprint regardless of the operating system it runs on. This cross-platform consistency, combined with low runtime overhead, differentiates it from approaches that rely on JavaScript-level patching or runtime injection. 

However, fingerprint control is only one part of a complete privacy setup. Real-world effectiveness depends on aligning network and browser signals. Pairing BotBrowser with well-configured proxy infrastructure, including matching locale where appropriate and using residential IPs when realism matters, helps ensure consistency across both application and network layers.

Start with the free demo profiles, validate the output with CreepJS, and move to PRO or Enterprise tiers once a project requires automation features such as CDP-based Playwright control or per-context fingerprints.