Noureddine RAMDI / BotBrowser: a Chromium core with per-context fingerprint bundles for cross-platform privacy uniformity

Created Tue, 05 May 2026 13:37:39 +0000 Modified Mon, 06 Jul 2026 15:16:10 +0000
1047 Words
github-stars typescript chromium privacy fingerprinting automation proxy

botswin/BotBrowser

BotBrowser tackles the persistent problem of browser fingerprinting in a unique way: it offers cross-platform fingerprint uniformity by running multiple independent fingerprint profiles inside a single Chromium process. This approach preserves a consistent privacy posture whether you’re on Windows, macOS, Linux, Android, or even WebView, while also saving substantial memory compared to traditional anti-detect browsers.

What BotBrowser does and its architecture

At its core, BotBrowser is a modified Chromium-based browser engine designed to provide deterministic, uniform browser fingerprints across multiple platforms. It modifies Chromium’s rendering and API layers to inject deterministic noise into fingerprinting surfaces like Canvas, WebGL, WebGPU, and AudioContext. This noise injection operates in multiple layers, ensuring that even subtle fingerprint vectors remain indistinguishable across different environments.

A key architectural innovation is the per-context fingerprint bundles. Unlike typical anti-detect browsers that spawn a separate process for each profile — which inflates memory and CPU usage — BotBrowser runs multiple fingerprint profiles within a single browser process. Switching between these fingerprint contexts happens at millisecond latency, allowing efficient multi-profile management without the overhead of process spawning.

The browser also integrates Full-Proxy QUIC/STUN tunneling, encapsulating UDP traffic over SOCKS5 proxies to prevent geo-metadata leakage. This is critical because many fingerprinting and tracking systems attempt to infer physical location via network metadata, and this tunneling approach closes that vector.

BotBrowser supports popular automation frameworks like Playwright and Puppeteer with Chrome DevTools Protocol (CDP) leak blocking, making it suitable for automation scenarios that require stealth. It even includes a distributed privacy consistency validation system called Mirror, which helps ensure fingerprint uniformity in varied environments.

Under the hood, BotBrowser is primarily implemented in TypeScript, building on the Chromium codebase with custom native and JavaScript modules to handle noise injection, proxying, and fingerprint management.

Technical strengths, tradeoffs, and code quality

What sets BotBrowser apart is its per-context fingerprint architecture. Traditional anti-detect browsers isolate profiles by spawning separate processes, which is straightforward but comes with a memory and CPU cost. BotBrowser’s approach to multiplex multiple fingerprints within a single process reduces memory use by about 29% at scale, according to their benchmarks, while maintaining Speedometer 3.0 performance within 1% of stock Chrome. This is a notable engineering feat.

The deterministic multi-layer noise injection is another strength. Instead of randomizing fingerprint vectors, which can cause inconsistencies detectable by trackers, BotBrowser applies deterministic noise that remains consistent per profile. This consistency is crucial because trackers often look for conflicting fingerprint signals as a detection heuristic.

The QUIC/STUN tunneling over SOCKS5 proxy is a practical solution to a less-discussed problem: many proxy setups leak UDP metadata, which can betray the user’s real location or network environment. BotBrowser’s layered tunneling prevents this, enhancing geo-privacy.

The code quality, from what is visible, reflects a strong focus on performance and maintainability. The integration with Playwright and Puppeteer is thoughtfully designed to block CDP leaks, a common source of automation detection. The README and docs provide comprehensive guidance, indicating a well-maintained project.

The tradeoffs include additional complexity in managing per-context fingerprint state and proxy tunneling, which might introduce challenges in debugging or extending the browser. Also, while memory savings are significant at scale, single-instance users may not feel the same benefit. Lastly, using proxy tunneling requires infrastructure knowledge and setup, which might be a barrier for some users.

Quick start with BotBrowser

The project provides clear quick start instructions to get up and running with BotBrowser:

Step 1: Download

  • Grab the latest release for your OS
  • Obtain a demo profile (any .enc file)

Step 2: Launch

  • GUI users can use BotBrowserLauncher for one-click profile selection and multi-instance management

  • CLI example (Windows):

chrome.exe --bot-profile="C:\absolute\path\to\profile.enc" --user-data-dir="%TEMP%\botprofile_%RANDOM%"

macOS and Linux commands follow the same pattern; full instructions are in INSTALLATION.md.

Step 3: Verify

  • Visit fingerprint observatories like CreepJS to confirm the browser fingerprint is uniform
  • Timezone, locale, and language settings are auto-derived from your proxy/IP, but can be overridden via CLI

Additionally, there’s a minimal Playwright example to automate browsing with BotBrowser:

const browser = await chromium.launch({
  headless: true,
  executablePath: BOTBROWSER_EXEC_PATH,
  args: [`--bot-profile=${BOT_PROFILE_PATH}`,
  '--proxy-server=socks5://usr:pwd@127.0.0.1:8989']
});
const page = await browser.newPage();
await page.addInitScript(() => { delete window.__playwright__binding__; delete window.__pwInitScripts; });
await page.goto('https://abrahamjuliot.github.io/creepjs/');

Notes:

  • Use --user-data-dir with a unique temporary folder to avoid conflicts with other Chromium instances
  • Use --proxy-server or per-context proxies for geo-privacy
  • Avoid framework-specific proxy auth options like page.authenticate(), which can leak location info

Who should consider BotBrowser?

BotBrowser is aimed squarely at privacy researchers, security professionals, and developers working on defensive benchmarking against sophisticated tracking systems. It supports testing against over 31 known tracking providers including Cloudflare, Akamai, Kasada, and DataDome.

The per-context fingerprint architecture is particularly relevant if you need to run many profiles efficiently on a single machine without the overhead of multiple processes. It’s also a good fit for automation scenarios requiring stealth and consistent fingerprinting across platforms.

That said, BotBrowser is not a casual browser replacement for everyday web surfing. It requires some familiarity with proxies, fingerprinting concepts, and automation frameworks. The proxy tunneling setup, while powerful, adds operational complexity.

In production, this means you get a browser that balances strong privacy guarantees, automation compatibility, and performance, but at the cost of a steeper learning curve and infrastructure needs.

Overall, BotBrowser pushes the envelope on privacy-focused browser engineering with a thoughtful architecture that balances resource efficiency and fingerprint consistency. It’s worth a look if your work involves anti-detection, privacy research, or automation at scale.

→ GitHub Repo: botswin/BotBrowser ⭐ 2,415 · TypeScript