README.md
May 31, 2026 · View on GitHub
BotBrowser
Advanced Privacy Browser Core with Unified Fingerprint Defense 🚀
Identical privacy posture on any OS • Cross-platform & WebView simulation • Fingerprint protection validated across 31+ tracking scenarios
What Is BotBrowser?
BotBrowser is a privacy-first browser core designed to protect users from browser fingerprinting, a technique recognized as a privacy threat by W3C, major browser vendors, privacy regulators, and academic research (see references). It keeps fingerprint signals uniform across every platform, preventing tracking systems from collecting and correlating data to identify users. Run the same profile on Windows, macOS, or Linux and the fingerprint posture stays identical each time.
All engineering focuses on privacy research, cross-platform tracking-resistance validation, and maintaining protected environments for authorized defensive benchmarking. Review the project Legal Disclaimer and Responsible Use Guidelines before using the software.
Why BotBrowser
What makes BotBrowser different: Cross-platform privacy browser core with unified fingerprint technology that prevents tracking data collection and device linkage.
| High-Fidelity, Always-Current Profiles including Android WebView, built on the latest stable Chromium so fingerprints always match current browser behavior and trackers cannot key on stale engines | Network Stack Parity with Full-Proxy QUIC/STUN (UDP over SOCKS5) delivers Chromium-level tunneling so geo metadata does not leak and privacy labs maintain clean transport parity |
| Advanced Programmatic Control offers Playwright/Puppeteer integration with CDP leak blocking so privacy tooling leaves no telemetry residue | Distributed Privacy Consistency lets you verify privacy protection across multiple browser instances simultaneously with Mirror, synchronizing input and validating privacy posture in parallel |
| Per-Context Fingerprint enables independent fingerprint bundles per BrowserContext without spawning new processes, with millisecond-level switching and reduced memory overhead | Zero-Overhead Performance adds no measurable latency: Speedometer 3.0 within <1% of stock Chrome, zero fingerprint API overhead across macOS/Linux/Windows, 29% memory savings at scale with Per-Context Fingerprint, and a Trimmed Build (ENT Tier3) delivering 62% lower wall time and 85% faster per-context spin-up on Linux x64 |
Cross-Platform Fingerprint Protection
- Single profile, every host OS: identical UA, screen metrics, touch surfaces, fonts, and device APIs on Windows, macOS, Linux (ENT Tier1), Android (PRO), and WebView (ENT Tier3) so trackers see the same fingerprint everywhere.
- Built-in configuration handles touch simulation, device metrics, and locale/timezone detection from the proxy IP while still allowing CLI overrides when privacy experiments require them.
- Quick demos: ▶️ CreepJS Android • ▶️ Iphey • ▶️ Pixelscan
Getting Started
Quick Start
Step 1: Download
- Latest release for your OS
- Demo profile (any
.encfile)
Step 2: Launch
- GUI: Use BotBrowserLauncher for one-click profile selection and multi-instance management
- CLI (use absolute paths):
chrome.exe --bot-profile="C:\absolute\path\to\profile.enc" --user-data-dir="%TEMP%\botprofile_%RANDOM%" - macOS/Linux commands follow the same pattern; see INSTALLATION.md for full instructions.
Step 3: Verify
- Visit CreepJS or your preferred tracking observatory to confirm identical privacy posture.
- Timezone/locale/language auto-derive from your proxy/IP; override via CLI only when needed.
Minimal Playwright Example
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'] // or: http://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-dirwith a unique temporary folder to avoid conflicts with running Chromium instances - Prefer
--proxy-serveror per-context proxies (ENT Tier1); auto timezone/locale detection applies in both cases - Avoid framework-specific proxy/auth options (e.g.,
page.authenticate()), which disable BotBrowser's geo-detection and may leak location information
Examples: Playwright • Puppeteer
More options:
- Framework-less approach:
--bot-script+ CDP (privileged context, earlier hook, fewer artifacts) - Docker: docker/README.md
- Full flags: CLI_FLAGS.md
Builds
BotBrowser ships in two builds. Both share the same fingerprint protection model, the same profile format, the same CLI flag surface, and the same CDP commands.
| Standard Build | Trimmed Build (ENT Tier3) | |
|---|---|---|
| Distribution | Public releases | Enterprise channel only |
| Built for | Long-running and interactive sessions | Short-session, high-concurrency automation |
| Browser feature surface | Full | Tuned for short-session workloads |
| Fingerprint protection | Same | Same |
| Per-Context Fingerprint | Same | Same |
| Profile compatibility | Same | Same |
Linux x64 benchmark (400 official samples, 1..20 contexts × 10 repeats × 2 builds): Trimmed Build cuts wall time by 62%, per-context creation by 85%, first navigation by 38%, CPU peak by 68%, PSS peak by 31% versus Standard, with 100% success rate and 0 residual processes for both builds.
Trimmed Build is the right choice when context spin-up dominates total wall time, when CPU peak per context limits density, or when shared memory is the binding constraint. Standard Build remains the right choice for interactive workflows and scenarios that exercise the full browser feature surface.
Product overview, engineering design, FAQ: TRIMMED_BUILD.md. Full performance table: BENCHMARK.md#trimmed-build. Access: Enterprise or Pricing.
Feature Reference
Configuration priority: CLI flags (highest) > Profile configs > defaults. Timezone, locale, and language auto-derive from your proxy IP.
Network & Proxy
| Feature | Reference | Guide |
|---|---|---|
| Proxy with embedded credentials (HTTP/SOCKS5/SOCKS5H) | Proxy Configuration | Guide |
| Regex-based proxy routing rules | --proxy-bypass-rgx | Guide |
| Per-context proxy with auto geo-detection | Per-Context Fingerprint | Guide |
| Dynamic proxy switching at runtime | Dynamic Proxy Switching | Guide |
| UDP over SOCKS5 (QUIC/STUN tunneling) | UDP over SOCKS5 | Guide |
| Local DNS solver | --bot-local-dns | Guide |
| Port protection for local services | --bot-port-protection | Guide |
| WebRTC leak protection (SDP/ICE control) | WebRTC Leak Protection | Guide |
Fingerprint & Rendering
| Feature | Reference | Guide |
|---|---|---|
| Canvas / WebGL / WebGPU deterministic noise | Multi-Layer Noise | Canvas · WebGL |
| AudioContext noise calibration | Multi-Layer Noise | Guide |
| Text metrics & ClientRects noise | Multi-Layer Noise | Guide |
| Deterministic noise seeds (reproducible per-tenant) | --bot-noise-seed | Guide |
| Performance timing protection (27 browser operations) | Performance Timing Protection | Guide |
| Stack depth fingerprint control (main/Worker/WASM) | Stack Depth Control | Guide |
| Network information privacy (rtt/downlink/effectiveType) | Network Info Privacy | Guide |
| CPU core scaling protection | CPU Core Scaling | Guide |
| Cross-platform font engine (Win/Mac/Android) | Font Engine | Guide |
| GPU simulation on headless servers | Headless Compatibility | Guide |
Identity & Platform
| Feature | Reference | Guide |
|---|---|---|
| Cross-platform profile portability (Win / Mac / Linux) | Advanced Features | Guide |
| Browser brand switching (Chrome/Edge/Brave/Opera) | Profile Overrides | Guide |
| Custom User-Agent with full userAgentData control | Profile Overrides | Guide |
| Client Hints alignment (DPR, device-memory, UA-CH) | Browser & OS | Guide |
| Android WebView emulation | Profile Overrides | Guide |
| Chrome behavior emulation (HTTP/2, HTTP/3, headers) | Chrome Behavior |
Automation & Scripting
| Feature | Reference | Guide |
|---|---|---|
| Playwright / Puppeteer integration | Examples | Playwright · Puppeteer |
| Framework-less bot-script (chrome.debugger API) | --bot-script | Guide |
| Per-context fingerprint (multiple profiles per process) | Per-Context Fingerprint | Guide |
| Console message suppression | Behavior Toggles | Guide |
| Headless / GUI parity | Headless Compatibility | Guide |
| Mirror: distributed privacy consistency | Mirror Documentation | Guide |
| CanvasLab: Canvas 2D / WebGL / WebGL2 recorder | --bot-canvas-record-file | Guide |
| AudioLab: Web Audio API recorder | --bot-audio-record-file | Guide |
| V8Log Forensics | --bot-v8-log | Guide · Tool |
Session & Behavior
| Feature | Reference | Guide |
|---|---|---|
| Cookie management (inline JSON or file) | --bot-cookies | Guide |
| Bookmark injection | --bot-bookmarks | Guide |
| History injection (random or precise count) | Behavior Toggles | Guide |
Incognito X-Client-Data consistency | Behavior Toggles | Guide |
| Always-active windows (anti-focus-tracking) | Active Window | Guide |
| Custom HTTP headers (CLI + CDP) | --bot-custom-headers | Guide |
| Plaintext storage access (cookies, localStorage) | Storage Access | Guide |
| Precision FPS simulation | Behavior Toggles | Guide |
| Timing scale (performance.now compression) | Behavior Toggles | Guide |
| Window/screen dimension control | Profile Overrides | Guide |
| Mobile screen orientation control | --bot-config-orientation | Guide |
Fingerprint Protection Implementation: Privacy Controls → Technical Design → Validation
This reference maps privacy protection goals to BotBrowser implementation details and validation evidence.
| Privacy Protection | Implementation | Reference |
|---|---|---|
| API standardization | navigator.webdriver standardized across all platforms so trackers cannot use API presence/absence as identification signal | ADVANCED_FEATURES#Chrome Behavior Emulation |
| Execution environment protection | Isolated execution context prevents framework artifacts from exposing privacy leaks | ADVANCED_FEATURES#Playwright/Puppeteer Integration |
| Graphics rendering consistency | Deterministic noise across Canvas, WebGL, WebGPU, and audio ensures protected fingerprints even in GPU-dependent scenarios | ADVANCED_FEATURES#Graphics & Rendering Engine |
| GPU fingerprint uniformity | Canvas and WebGPU rendering shares deterministic properties so GPU probes like WebBrowserTools return authentic results | CHANGELOG#2025-12-08 |
| Typography consistency | Embedded font engines for Windows, macOS, Linux, and Android ensure text rendering remains identical across platforms | ADVANCED_FEATURES#Cross-Platform Font Engine |
| Font availability uniformity | DOM queries return authentic font lists from embedded bundles so host system fonts cannot leak platform identity | ADVANCED_FEATURES#Cross-Platform Font Engine |
| Device capabilities | Profile-based device properties maintain protected device claims across all platforms | Profile Configs |
| Network topology privacy | WebRTC signaling stays protected through SDP and ICE controls preventing network topology leakage | ADVANCED_FEATURES#WebRTC Leak Protection |
| User agent coherence | Browser brand and version parity prevents UA string from revealing platform differences | CLI_FLAGS#Profile Configuration Override Flags |
| Header to API parity | Client Hints headers DPR, device-memory, and UA-CH align with JavaScript reported values preventing header based identification | ADVANCED_FEATURES#Browser & OS Fingerprinting |
| Execution mode parity | GPU, WebGPU, and media signals remain identical whether running headless or in GUI mode | ADVANCED_FEATURES#Headless & Incognito Compatibility |
| DNS privacy | Use local DNS solver (ENT Tier1) for private resolution that avoids DNS leaks and provider restrictions, or use SOCKS5H to keep DNS within proxy tunnels | CLI_FLAGS#Enhanced Proxy Configuration |
| Public IP discovery | Customizable IP lookup backend for geo derivation via --bot-ip-service (supports comma-separated endpoints; BotBrowser races them and uses the fastest successful response) | CLI_FLAGS#Enhanced Proxy Configuration |
| Protocol conformance | HTTP/2 and HTTP/3 behavior matches Chrome specifications preventing protocol based differentiation | ADVANCED_FEATURES#Chrome Behavior Emulation |
| TLS fingerprint protection | JA3, JARM, and ALPN parameters optimized for uniform TLS negotiation across platforms | CHANGELOG |
| DRM capability consistency | Widevine persistent license support with platform-appropriate license negotiation prevents tracking via EME capability fingerprinting | ADVANCED_FEATURES |
| Authentication capability uniformity | WebAuthn client capabilities return platform-specific values preventing tracking via Touch ID, Bluetooth authenticator, and payment extension detection | ADVANCED_FEATURES |
Fingerprint Protection Matrix: Cross-Platform Coverage
| Category | Sample Capabilities |
|---|---|
| Graphics | Canvas/WebGL rendering, GPU micro-benchmarks, texture hash configuration |
| Network | WebRTC SDP configuration, proxy auth, connection management |
| Platform | Font fallback chains, cross-worker protection, OS-specific features |
| Performance | FPS simulation, memory timing, animation frame optimization |
Advanced Features (architecture & design) → | CLI Flags (all options) →
Fingerprint Protection Validation
Fingerprint protection validated across 31+ tracking scenarios. See DISCLAIMER for authorized use.
Cross-Platform Protection Validation
- Windows Profile on macOS: Fingerprint protection maintained so privacy defenses remain effective across platforms
- Android Emulation on Desktop (PRO): Mobile API parity enables fingerprint testing for cross-device privacy research
- Headless vs GUI Mode: Identical fingerprint behavior ensures privacy validation results remain effective across execution contexts
Complete Validation Results & Research Data →
Engine Internals
BotBrowser's engine is built in-house on top of Chromium, with no forks or external project dependencies. Selected patch examples, build configurations, and the Chromium source directory tree are published in patches/. The full core remains proprietary.
Resources & Support
Documentation
- Guides - Step-by-step guides for proxy, fingerprint, identity, platform emulation, and deployment
- llms.txt - Indexed entry point for LLMs (project summary plus links to core docs and guides)
- Installation Guide - Platform-specific setup, Docker deployment, troubleshooting
- Advanced Features - Architecture and design details
- CLI Flags Reference - Core and extended runtime flags with examples
- Profile Configuration - Profile JSON field reference
- Validation Results - Research data across 31+ tracking scenarios
- Performance Benchmark - Speedometer 3.0, fingerprint API overhead, and scale performance data
Support Channels
| Website | Documentation, guides, blog | botbrowser.io |
| Technical questions, source code access | support@botbrowser.io | |
| Telegram | Community support, quick questions | @botbrowser_support |
Responsible Use
- Review the detailed Responsible Use Guidelines and Legal Disclaimer before requesting binaries or premium profiles.
- Maintain written authorization for every environment you test, and record the synthetic data sets you rely on.
- Contact the maintainers at support@botbrowser.io if you observe suspicious activity or need to report an abuse incident.
Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.