Profile Management

Manage BotBrowser profile files, versions, and lifecycle for reproducible fingerprint protection.

Prerequisites

• BotBrowser binary installed on your system. See INSTALLATION.md for platform-specific setup.
• Basic familiarity with running BotBrowser from the command line or via a framework (Playwright, Puppeteer).

Quick Start

1. Download a profile

Download profile files from GitHub Releases . Each release includes .enc profile files matching the Chrome version of the binary.

2. Launch with a profile

chromium-browser \
  --bot-profile="/absolute/path/to/profile.enc" \
  --user-data-dir="$(mktemp -d)"

3. Verify it works

Visit CreepJS  or BrowserLeaks  to confirm the fingerprint is active. See First Verification for a complete verification checklist.

How It Works

A BotBrowser profile is an encrypted file that defines the complete browser environment. Think of it as a device model: it specifies the hardware, software, and rendering characteristics that make up a browser fingerprint.

What a profile contains:

What a profile does not contain: Proxy settings, timezone, locale, cookies, or browsing history. These are session-specific and configured separately through CLI flags or the configs block.

The device model analogy

A profile is like a specific hardware configuration, for example “MacBook Pro M4 Max”:

• User A uses the same profile with a US proxy, English locale, and EST timezone.
• User B uses the same profile with a German proxy, German locale, and CET timezone.
• User C uses the same profile with a Japanese proxy, Japanese locale, and JST timezone.

All three appear to use the same device type, but each has a distinct identity defined by their session settings.

Profile Types

Demo Profiles

Demo profiles are included in the profiles/  directory for evaluation and testing.

Limitations:

• Limited-time privacy research use only
• No headless mode support
• No automation framework support (Puppeteer, Playwright)
• No extension loading
• Not suitable for production use, as demo profiles are widely distributed

Premium Profiles

Premium profiles provide unique configurations designed for authorized fingerprint protection and privacy research.

Features:

• Unique configurations for controlled studies
• Privacy-compliant synthetic data based on aggregated device patterns
• Suitable for production research with automation frameworks
• Headless mode support
• Extension loading support

To access premium profiles, contact:

• Email: support@botbrowser.io
• Telegram: @botbrowser_support 

Profile Versions

Profiles are versioned to match BotBrowser binary versions. The binary and profile Chrome versions must match.

Version matching rule: A BotBrowser v146 binary requires v146 profiles. Using mismatched versions will result in a silent failure where the browser runs without fingerprint protection.

Checking available versions

Browse the profiles/  directory on GitHub:

• profiles/stable/ contains current stable profiles
• profiles/canary/ contains early development profiles
• profiles/archive/ contains previous versions

Profile Configuration

You can customize profile behavior through two methods: the configs block in the profile JSON, or CLI flags that override profile settings at runtime.

Configuration priority (highest to lowest)

1. CLI --bot-config-* flags. Highest priority. Always overrides profile settings.
2. Profile configs block. Medium priority. Overrides profile defaults.
3. Profile default values. Lowest priority. Built-in profile data.

CLI overrides (recommended)

CLI flags are the preferred way to customize behavior because they do not require editing encrypted profile files:

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-timezone=Europe/Berlin \
  --bot-config-locale=de-DE \
  --bot-config-languages=de-DE,de,en-US,en \
  --bot-config-webrtc=disabled \
  --user-data-dir="$(mktemp -d)"

Profile configs block

For settings that should persist across sessions, add a configs block to the profile JSON:

{
  "configs": {
    "locale": "auto",
    "languages": "auto",
    "timezone": "auto",
    "colorScheme": "light",
    "webrtc": "profile",
    "noiseCanvas": true,
    "noiseWebglImage": true,
    "noiseAudioContext": true
  },
  "key": { /* ... */ },
  "version": { /* ... */ },
  "profile": { /* ... */ }
}

Place the configs block before the key block in the JSON structure.

For the complete list of configurable fields, see Profile Configuration Guide.

Common Scenarios

Random profile selection from a directory

Place multiple .enc files in a directory and let BotBrowser pick one randomly on each startup:

chromium-browser \
  --bot-profile-dir="/path/to/profiles/" \
  --user-data-dir="$(mktemp -d)"

This is useful for multi-instance deployments where you want fingerprint diversity without manual profile assignment.

Same profile, different identities

Use one profile with different session settings to create distinct user sessions:

# Session 1: US user
chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=socks5://user:pass@us-proxy.example.com:1080 \
  --bot-cookies='[{"name":"session","value":"us-user","domain":".example.com"}]' \
  --user-data-dir="$(mktemp -d)" &
 
# Session 2: German user
chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=socks5://user:pass@de-proxy.example.com:1080 \
  --bot-config-timezone=Europe/Berlin \
  --bot-config-locale=de-DE \
  --bot-cookies='[{"name":"session","value":"de-user","domain":".example.com"}]' \
  --user-data-dir="$(mktemp -d)" &

Cross-platform compatibility

The same profile file works on Windows, macOS, and Linux. BotBrowser handles platform-specific differences at the engine level:

• Windows host running a macOS profile: BotBrowser renders fonts, graphics, and system properties as if running on macOS.
• macOS host running a Windows profile: Navigator properties, screen metrics, and platform strings match a Windows environment.
• Linux host running an Android profile: Touch events, mobile APIs, and device metrics match an Android device.

Platform compatibility tiers:

• Windows and macOS profiles work on all platforms.
• Android profiles require a PRO subscription.
• Ubuntu/Linux binaries require ENT Tier1.

Troubleshooting / FAQ

Next Steps

• Profile Configuration Guide. Complete reference for all configurable fields.
• CLI Flags Reference. All available flags, including --bot-config-* overrides.
• CLI Recipes. Common flag combinations for typical scenarios.
• First Verification. Verify your setup is working correctly.
• Playwright Guide. Use profiles with Playwright.
• Puppeteer Guide. Use profiles with Puppeteer.

Related documentation: Profiles Directory  | Profile Configuration | CLI Flags Reference

Legal Disclaimer & Terms of Use  • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.