BotBrowser CLI Flags Reference
Use this reference to find flag syntax, availability, configuration timing, and the primary setup guide. For terms of use, see the Legal Disclaimer and Responsible Use Guidelines.
Smart auto-configuration: BotBrowser derives timezone, locale, and languages from your IP/proxy. Override only when you need a specific setup.
License tiers: Some flags show tier hints in parentheses (PRO, ENT Tier1/Tier2/Tier3/Tier4); those options are subscription-gated.
Table of Contents
- How to Use This Reference
- Flag Directory
- Core BotBrowser Flags
- Enhanced Proxy Configuration
- BotBrowser Customization
- Profile Configuration Override Flags
- Mirror: Distributed Privacy Consistency
- Usage Examples
How to Use This Reference
Every flag has one primary guide. The detailed reference below provides syntax, accepted values, defaults where applicable, examples, and compatibility notes.
Configuration timing and scope:
| Label | Type | Meaning |
|---|---|---|
Startup | Timing | Pass when launching the browser process. |
Context | Timing | Supply through Per-Context Fingerprint before the first page or worker starts. This interface requires ENT Tier3. |
Live | Timing | The primary guide documents a runtime update path and its required tier. |
Browser-wide | Scope | Applies to the browser process rather than an individual BrowserContext. |
Profile-dependent means the active profile package must include that capability.
Identity-bearing settings must be applied before the first page or worker starts. See Context Identity Lifecycle.
Configuration priority remains CLI flags, then profile configs, then profile defaults.
Flag Directory
Jump to Profiles, Network, Session, Identity, Display, Rendering, or Mirror.
Each entry shows availability and the primary guide. The guide documents startup, BrowserContext, and runtime paths where supported.
Profiles and Startup
--bot-profile(Core): Profile Management--bot-profile-dir(Core): Profile Management--bot-title(Core): CLI Recipes
Proxy, PAC, DNS and WebRTC
--proxy-server(Core; Context/Live ENT Tier3): Proxy Configuration--disable-quic(Standard Chromium): UDP over SOCKS5--proxy-pac-url(Core PAC; callback ENT Tier3): PAC Request Policy--proxy-ip(ENT Tier1): Proxy and Geolocation--proxy-bypass-rgx(PRO): Proxy Selective Routing--bot-port-protection(PRO): Port Protection--bot-local-dns(ENT Tier1): DNS Leak Prevention--bot-ip-service(Core): Proxy and Geolocation--bot-config-webrtc(Core): WebRTC Leak Prevention--bot-webrtc-ice(ENT Tier1): WebRTC Leak Prevention
Session, Automation and Diagnostics
--bot-cookies(PRO): Cookie Management--bot-bookmarks(Core): Bookmark Seeding--bot-canvas-record-file(Core): CanvasLab--bot-audio-record-file(Core): AudioLab--bot-v8-log(Profile-dependent): V8Log--bot-v8-log-dir(Profile-dependent): V8Log--bot-script(Core): Bot Script--bot-custom-headers(PRO): Custom HTTP Headers--bot-disable-debugger(Core): Automation Consistency--bot-disable-console-message(ENT Tier1): Console Suppression--bot-inject-random-history(PRO): History Seeding--bot-enable-variations-in-context(ENT Tier2): Incognito Fingerprinting--bot-always-active(PRO): Active Window
Identity, Locale and Platform
--bot-config-browser-brand(ENT Tier2 / WebView ENT Tier3): Browser Brand Alignment--bot-config-brand-full-version(ENT Tier2): Browser Brand Alignment--bot-config-ua-full-version(ENT Tier2): Custom User-Agent--bot-config-languages(ENT Tier1): Timezone, Locale and Language--bot-config-locale(ENT Tier1): Timezone, Locale and Language--bot-config-timezone(ENT Tier1): Timezone, Locale and Language--bot-config-location(ENT Tier1): Timezone, Locale and Language--bot-config-platform(ENT Tier3): Custom User-Agent--bot-config-platform-version(ENT Tier3): Custom User-Agent--bot-config-model(ENT Tier3): Custom User-Agent--bot-config-architecture(ENT Tier3): Custom User-Agent--bot-config-bitness(ENT Tier3): Custom User-Agent--bot-config-mobile(ENT Tier3): Device Emulation
Display, Input and Appearance
--bot-config-window(Core): Screen and Window--bot-config-screen(Core): Screen and Window--bot-config-keyboard(Core): Device Emulation--bot-config-fonts(Core): Font Fingerprinting--bot-mobile-keyboard(Profile-dependent): Device Emulation--bot-config-orientation(Core): Device Emulation--bot-config-color-scheme(Core): CSS Signal Consistency--bot-config-disable-device-scale-factor(Core): Screen and Window--bot-mobile-force-touch(Core): Device Emulation
Rendering, Media and Protection
--bot-config-webgl(Core): WebGL Fingerprinting--bot-config-webgpu(Core): WebGPU Fingerprint Protection--bot-config-noise-webgl-image(Core): WebGL Fingerprinting--bot-config-noise-canvas(Core): Canvas Fingerprinting--bot-config-noise-audio-context(Core): Audio Fingerprinting--bot-config-noise-client-rects(Core): Font Fingerprinting--bot-config-noise-text-rects(Core): Font Fingerprinting--bot-config-speech-voices(Core): Speech Synthesis--bot-config-media-devices(Core): Media Devices Privacy--bot-config-media-types(Core): MIME and Codec--bot-noise-seed(ENT Tier2): Noise Seed Reproducibility--bot-fps(ENT Tier2): FPS Control--bot-video-fps(ENT Tier2): FPS Control--bot-js-heap-size-limit(Core): Storage and Memory--bot-storage-quota(Core): Storage and Memory--bot-time-scale(ENT Tier2): Performance Fingerprinting--bot-time-seed(ENT Tier2): Performance Fingerprinting--bot-stack-seed(ENT Tier2): Stack Depth--bot-network-info-override(Core): Navigator Properties--bot-gpu-emulation(ENT Tier2): Linux GPU Backend
Mirror
--bot-mirror-controller-endpoint(ENT Tier3): Mirror Distributed--bot-mirror-client-endpoint(ENT Tier3): Mirror Distributed
Core BotBrowser Flags
--bot-profile
The foundation of BotBrowser’s privacy features.
Specifies the path to the BotBrowser profile file (.enc).
Primary guide: Profile Management
--bot-profile="/absolute/path/to/profile.enc"Notes:
- The profile determines the fingerprint, OS emulation, and privacy controls
- A profile is reusable and can launch multiple browser processes or BrowserContexts; it is not a one-browser slot
- Use a unique
--user-data-dirfor every browser process to keep storage and session state independent - Use a profile package that matches your BotBrowser major version. BotBrowser 150 and newer profile packages are available through subscription or support at support@botbrowser.io or @botbrowser_support; legacy demo profiles remain in the profiles directory for older evaluation lines.
--bot-profile-dir
Random profile selection for fingerprint diversity.
Primary guide: Profile Management
Specify a directory containing multiple .enc profile files. BotBrowser will randomly select one profile on each startup for fingerprint diversity without manual configuration.
--bot-profile-dir="/absolute/path/to/profiles/directory"Notes:
- Each startup randomly selects a different profile from the directory
- Useful for multi-instance deployments requiring fingerprint variation
- Cannot be used together with
--bot-profile(directory takes precedence if both are specified) - Can be used at BrowserContext creation time through Per-Context Fingerprint when a context should select its own profile from a directory
Enhanced Proxy Configuration
Enhanced --proxy-server with Embedded Credentials
BotBrowser extends the standard --proxy-server flag to accept embedded credentials in the URL.
Primary guide: Proxy Configuration
⚠️ Important: For authorized privacy research and fingerprint protection only. Do not use for unauthorized data collection.
# HTTP/HTTPS proxy with credentials
--proxy-server=http://username:password@proxy.example.com:8080
--proxy-server=https://username:password@proxy.example.com:8080
# SOCKS5 proxy with credentials
--proxy-server=socks5://username:password@proxy.example.com:1080
# SOCKS5H proxy with credentials (hostname resolution stays within tunnel)
--proxy-server=socks5h://username:password@proxy.example.com:1080Supported Protocols: HTTP, HTTPS, SOCKS5, SOCKS5H.
Proxy auth usernames: Structured proxy usernames can include additional separators such as , and |. This is useful for providers that encode routing hints inside the username, for example:
--proxy-server=socks5://user_abc,type_mobile,country_GB,session_1234:11111@portal.proxy.example.com:1080UDP over SOCKS5 (ENT Tier3)
ENT Tier3 adds built-in SOCKS5 UDP ASSOCIATE support with no extra flag required. When the proxy supports UDP, BotBrowser tunnels QUIC traffic and STUN probes over the proxy to keep network identity consistent.
Primary guide: UDP over SOCKS5
# UDP (QUIC/STUN) auto-tunneled when the SOCKS5 proxy supports UDP associate
--proxy-server=socks5://username:password@proxy.example.com:1080To keep SOCKS5 proxying but avoid QUIC/HTTP/3, add the standard --disable-quic flag. See UDP over SOCKS5.
--proxy-server=socks5://username:password@proxy.example.com:1080
--disable-quic--disable-quic affects QUIC/HTTP/3 only. WebRTC/STUN behavior still follows the UDP-over-SOCKS5 and WebRTC settings.
PAC-Like Request Callback (ENT Tier3)
ENT Tier3 profiles can use trusted PAC scripts for request callback workflows while preserving standard PAC routing. Configure PAC through the standard --proxy-pac-url flag and keep the PAC source explicit.
Primary guide: PAC Request Policy
# Local PAC file
--proxy-pac-url=file:///absolute/path/to/proxy.pac
# Controlled loopback PAC server
--proxy-pac-url=http://127.0.0.1:8080/proxy.pacStandard FindProxyForURL(url, host) behavior remains available for normal routing. Approved profiles and trusted PAC sources can also define BotBrowser’s request callback:
function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
return "CONTINUE";
}Supported callback results:
- Continue or stop:
CONTINUE,BLOCK - Capture:
CAPTURE,CAPTURE_TAG <tag>,CAPTURE_FILE <path> - Synthetic response:
RESPONSE <raw_http_response_b64>,RESPONSE_FILE <path> - Standard PAC route:
DIRECT,PROXY,HTTPS,SOCKS,SOCKS4,SOCKS5
PAC and callback routes can include credentials, for example SOCKS5 user:pass@proxy.example.com:1080. Capture records are written only when CAPTURE and CAPTURE_FILE <path> are returned together. Synthetic responses are limited to approved file: and data: PAC sources and fail closed when response input is invalid. See PAC Request Policy.
Use this when request-aware policy should stay in PAC routing instead of CDP-level request interception, especially for workflows that need help preserving HTTP/2 connection and stream continuity while directing selected requests to different routes.
--proxy-ip (ENT Tier1)
Specify the proxy’s public IP to optimize performance.
Primary guide: Proxy and Geolocation
This skips per-page IP lookups and speeds up navigation.
--proxy-ip="203.0.113.1"Benefits:
- Eliminates IP detection overhead on each page load
- Faster browsing when using proxies
- Combine with
--bot-config-timezonefor protected region emulation
⚠️ Important:
- Browser-level proxy: use
--proxy-serverfor protected geo-detection across contexts - Per-context proxy (ENT Tier1): set different proxies via
createBrowserContext({ proxyServer })orBotBrowser.setBrowserContextFlagswith--proxy-server; BotBrowser auto-derives geo info in both cases. Guide: Per-Context Proxy - Avoid: framework-specific options like
page.authenticate()that disable BotBrowser’s geo-detection, which may leak location information
--proxy-bypass-rgx (PRO)
Define URL patterns via regular expressions for proxy routing control. Uses RE2 regex syntax. Matches against both hostname and full URL path (including HTTPS).
--proxy-bypass-rgx="\.js(\?|$)" # Bypass .js files
--proxy-bypass-rgx="\.(js|css|png|svg)(\?|$)" # Bypass static assets
--proxy-bypass-rgx="/api/public/|/static/" # Bypass specific paths
--proxy-bypass-rgx="cdn\.|\.google\.com$" # Bypass by domain patternJavaScript Usage:
Do NOT include quotes inside the value:
// Wrong - quotes become part of regex
launchArgs.push('--proxy-bypass-rgx="\\.js$"');
// Correct
launchArgs.push('--proxy-bypass-rgx=\\.js($|\\?)');
launchArgs.push('--proxy-bypass-rgx=example\\.com.*\\.js($|\\?)');In JavaScript strings: \\. becomes \., \\? becomes \?
Primary guide: Proxy Selective Routing
--bot-port-protection (PRO)
Protect local service ports (VNC, RDP, development servers, etc.) from being scanned. When enabled, BotBrowser prevents remote pages from detecting which services are running on localhost.
--bot-port-protectionCovers 30 commonly-probed ports across IPv4 (127.0.0.0/8), IPv6 (::1), and localhost. Can also be enabled via profile JSON (configs.portProtection).
Primary guide: Port Protection
--bot-local-dns (ENT Tier1)
Enable the local DNS solver. This keeps DNS resolution local instead of relying on a proxy provider’s DNS behavior, improving privacy and speed while avoiding common DNS poisoning paths. Part of Network Fingerprint Control.
--bot-local-dns
--bot-local-dns=true
--bot-local-dns=false
--bot-local-dns=8.8.8.8
--bot-local-dns=127.0.0.1:5353Accepted values:
- bare flag or
true: resolve proxy targets locally using the browser’s built-in resolver false: disable LocalDNS and let the proxy resolve namesIPorIP:port: resolve proxy targets through the specified DNS server only. Port defaults to53. Invalid values are treated asfalse.
When a custom DNS server is configured, BotBrowser does not use the system resolver if the chosen DNS returns no answer.
Practical notes:
- Helps when a proxy provider blocks or rewrites DNS lookups
- Useful when you want to avoid provider-side DNS policies and keep resolution behavior protected across runs
IP[:port]is recommended for deterministic environments where the upstream DNS must be explicit
Primary guide: DNS Leak Prevention
--bot-ip-service
Customize the public IP service used to discover your egress IP (and derive geo settings when auto-detection is enabled).
Primary guide: Proxy and Geolocation
--bot-ip-service="https://ip.example.com"You can provide multiple endpoints as a comma-separated list. For each navigation, BotBrowser uses a single endpoint at a time and only moves to the next one when the previous one is unavailable, keeping the public-IP source stable across the request lifecycle.
--bot-ip-service="https://ip1.example.com,https://ip2.example.com"BotBrowser Customization
--bot-title
Custom browser identification and session management.
Primary guide: CLI Recipes
Sets custom browser window title and taskbar/dock icon label.
--bot-title="MyBot Session 1"
--bot-title="Research Session"Features:
- Appears in the window title bar
- Shows on the taskbar/dock icon
- Displays as a label next to the Refresh button
- Useful for managing multiple instances
--bot-cookies (PRO)
Session restoration and cookie management.
Accepts cookie data as either inline JSON or from a file. In Per-Context Fingerprint workflows, cookies can be imported at BrowserContext creation time so each context starts with its own session state.
Inline JSON:
--bot-cookies='[{"url":"https://example.com","name":"session","value":"abc123","domain":".example.com"}]'From JSON file:
--bot-cookies="@path/to/cookies.json"Each cookie object must include a url field. Cookies without url are silently skipped.
Primary guide: Cookie Management
--bot-bookmarks
Pre-populate bookmarks for session preservation.
Accepts a JSON string containing bookmark data for startup.
--bot-bookmarks='[{"title":"Example","type":"url","url":"https://example.com"},{"title":"Folder","type":"folder","children":[{"title":"Example","type":"url","url":"https://example.com"}]}]'Primary guide: Bookmark Seeding
--bot-canvas-record-file
Canvas forensics and privacy validation.
Records all Canvas 2D, WebGL, WebGL2, and WebGPU API calls to a JSONL file for forensic analysis and replay.
CanvasLab recording is a diagnostic workflow. Profile-backed Canvas Replay is an ENT Tier4 capability for approved validation workflows that require deterministic graphics protection from embedded profile data.
--bot-canvas-record-file="/tmp/canvaslab.jsonl"Key Features:
- Complete Canvas 2D, WebGL, WebGL2, and WebGPU API call recording with full parameter serialization
- Deterministic capture (noise variance disabled during recording)
- JSONL format for easy parsing and analysis
- HTML replay viewer with WebGL enum reverse-lookup and source location mapping
Primary guide: CanvasLab | Tool
--bot-audio-record-file
Web Audio forensics and tracking analysis.
Records all Web Audio API calls to a JSONL file for forensic analysis of audio fingerprint collection.
--bot-audio-record-file="/tmp/audiolab.jsonl"Key Features:
- Complete Web Audio API recording: context creation, node creation, parameter setting, routing topology, data extraction
- Automatic detection of common audio fingerprinting patterns
- Sample previews (first/last 10 values, sums) for quick inspection
- Codec support queries (canPlayType, MediaSource.isTypeSupported)
- JSONL format for easy parsing with
jqor the interactive Audio Viewer
Primary guide: AudioLab | Tool
--bot-v8-log
V8Log browser-runtime forensics for authorized privacy validation sessions.
--bot-v8-log=sample
--bot-v8-log=full
--bot-v8-log=noneUse sample for the normal validation trace, full only when requested, and pair it with --bot-v8-log-dir.
--bot-v8-log-dir
Output directory for V8Log evidence files.
--bot-v8-log=sample
--bot-v8-log-dir="/tmp/botbrowser-v8log"Use an absolute directory path that already exists and is writable by the browser process.
--bot-script
Framework-less approach with a privileged JavaScript context.
Execute a JavaScript file right after BotBrowser starts in a privileged, non-extension context where chrome.debugger is available. In Per-Context Fingerprint workflows, bot scripts can also be attached at BrowserContext creation time.
--bot-script="path/to/script.js"Key Features:
- No framework dependencies: pure Chrome DevTools Protocol access
- Earlier intervention: runs before navigation
- Privileged context: full
chrome.debuggerAPI access - Isolated execution: framework artifacts do not appear in page context
Documentation: Chrome chrome.debugger API - https://developer.chrome.com/docs/extensions/reference/api/debugger/
Primary guide: Bot Script | Examples
--bot-custom-headers (PRO)
Inject custom HTTP request headers into all outgoing requests.
# JSON format with header name-value pairs
--bot-custom-headers='{"X-Custom-Header":"value","X-Another":"value2"}'JavaScript Usage:
Do NOT wrap the JSON value in extra quotes; the shell-style single quotes shown above are for Bash only. In JavaScript they become literal characters inside the flag value:
// Wrong - single quotes become part of the value
args.push(`--bot-custom-headers='${JSON.stringify(customHeaders)}'`);
// Correct
args.push("--bot-custom-headers=" + JSON.stringify(customHeaders));Configuration Methods:
- CLI flag:
--bot-custom-headers='{"Header":"value"}' - Profile JSON:
configs.customHeaders - CDP:
BotBrowser.setCustomHeaders(see below; also in CDP Quick Reference)
CDP Usage:
The BotBrowser.setCustomHeaders command must be sent to the browser-level CDP session, not a page-level session. Sending it to a page target will return ProtocolError: 'BotBrowser.setCustomHeaders' wasn't found.
Puppeteer:
const cdpSession = await browser.target().createCDPSession();
await cdpSession.send('BotBrowser.setCustomHeaders', {
headers: { 'x-requested-with': 'com.example.app' }
});Playwright:
const cdpSession = await browser.newBrowserCDPSession();
await cdpSession.send('BotBrowser.setCustomHeaders', {
headers: { 'x-requested-with': 'com.example.app' }
});Notes:
- Headers are added to all HTTP/HTTPS requests
- Useful for API authentication, session management, or request routing
- JSON format with string key-value pairs
Primary guide: Custom HTTP Headers
Profile Configuration Override Flags
High-priority configuration overrides: these CLI flags supersede profile settings.
BotBrowser supports command-line flags that override profile configuration values with the highest priority. These flags start with --bot-config- and directly map to profile configs properties.
Recommended: Use CLI flags instead of modifying profiles. They carry the highest priority and don’t require editing encrypted files. License tiers are indicated in parentheses where applicable.
Bot Configuration Overrides (--bot-config-*)
Flags that directly map to profile configs and override them at runtime.
Identity & Locale
--bot-config-browser-brand=chrome(ENT Tier2, webview requires ENT Tier3): Browser brand: chrome, chromium, edge, brave, opera, webview. WebKit-family identities are delivered through ENT Tier4 premium profiles. Guide: Browser Brand Alignment.
--bot-config-brand-full-version=142.0.3595.65(ENT Tier2): Brand-specific full version for UA-CH consistency. Guide: Browser Brand Alignment.
--bot-config-ua-full-version=142.0.7444.60(ENT Tier2): User agent version matching the Chromium major. Guide: Custom User-Agent.
--bot-config-languages=auto: Languages:auto(IP-based, default) or a value such asen-US,fr-FR(ENT Tier1). Guide: Timezone, Locale and Language.
--bot-config-locale=auto: Browser locale:auto(derived from IP/language, default) or a value such asen-USorfr-FR(ENT Tier1). Guide: Timezone, Locale and Language.
--bot-config-timezone=auto: Timezone:auto(IP-based, default),real(system), or an IANA timezone such asAmerica/New_York(ENT Tier1). Guide: Timezone, Locale and Language.
--bot-config-location=auto: Location:auto(IP-based, default),real(system GPS), or coordinates such as40.7128,-74.0060(ENT Tier1). Guide: Timezone, Locale and Language.
Custom User-Agent (ENT Tier3)
Build any browser identity with full userAgentData control. These flags work together with --user-agent to construct a complete, internally consistent browser identity.
--bot-config-platform=Android: Platform name: Windows, Android, macOS, Linux. Guide: Custom User-Agent.
--bot-config-platform-version=13: OS version string. Guide: Custom User-Agent.
--bot-config-model=SM-G991B: Device model, primarily for mobile profiles. Guide: Custom User-Agent.
--bot-config-architecture=arm: CPU architecture: x86, arm, arm64. Guide: Custom User-Agent.
--bot-config-bitness=64: System bitness: 32, 64. Guide: Custom User-Agent.
--bot-config-mobile=true: Mobile device flag. Guide: Device Emulation.
The --user-agent flag supports placeholders that get replaced at runtime:
{platform},{platform-version},{model}for device info{ua-full-version},{ua-major-version}for Chromium version{brand-full-version}for brand-specific version (Edge, Opera){architecture},{bitness}for CPU info
BotBrowser auto-generates matching navigator.userAgentData (brands, fullVersionList with proper GREASE) and all Sec-CH-UA-* headers. Values stay consistent across main thread, workers, and HTTP requests.
Note: UA/Engine Congruence: Keep
--bot-config-ua-full-versionaligned with your Chromium major version, and use--bot-config-brand-full-versionwhen a vendor’s cadence (Edge, Opera, Brave) diverges so UA-CH metadata stays internally protected.
Display & Input
--bot-config-window=<value>: Window dimensions with multiple formats. Guide: Screen and Window.profile- Use profile’s window settings (default for headless and Android profiles)real- Use actual system window dimensions (default for desktop headful)WxH- Direct size specification (e.g.,1920x1080), sets innerWidth/innerHeight with outerWidth/outerHeight auto-derived from profile bordersJSON- Full customization (e.g.,'{"innerWidth":1920,"innerHeight":1080,"devicePixelRatio":2}')
--bot-config-screen=<value>: Screen properties with multiple formats. Guide: Screen and Window.profile- Use profile’s screen settings (default for headless and Android profiles)real- Use actual system screen dimensions (default for desktop headful)WxH- Direct size specification (e.g.,2560x1440), sets width/height with availWidth/availHeight auto-derived from profileJSON- Full customization (e.g.,'{"width":2560,"height":1440,"availWidth":2560,"availHeight":1400}')
Headful note: Desktop profiles default to
realin headful mode, meaning the browser uses the actual system window and screen dimensions. To apply profile-defined dimensions in headful, set both--bot-config-window=profileand--bot-config-screen=profileexplicitly.
--bot-config-keyboard=profile: Keyboard settings: profile (emulated), real (system keyboard). Guide: Device Emulation.
--bot-config-fonts=profile: Font settings: profile (embedded), expand (profile + fallback), real (system fonts). Guide: Font Fingerprinting.
--bot-mobile-keyboard[=true|false]: Opt-in mobile keyboard visual viewport behavior. When enabled for a mobile profile, trusted user focus on an editable field reducesvisualViewport.heightwhile leaving the layout viewport unchanged. Default: false. Guide: Device Emulation.
--bot-config-orientation=<value>: Screen orientation for mobile profiles. Desktop profiles ignore this flag. Guide: Device Emulation.profile- Auto-detect from profile dimensions (default)landscape/portrait- Force orientation, automatically adjusting all related dimensions to matchlandscape-primary,landscape-secondary,portrait-primary,portrait-secondary- Explicit orientation with specific angle
--bot-config-color-scheme=light: Color scheme: light, dark. Guide: CSS Signal Consistency.
--bot-config-disable-device-scale-factor: Disable device scale factor: true, false. Guide: Screen and Window.
Rendering, Noise & Media/RTC
--bot-config-webgl=profile: WebGL: profile (use profile), real (system), disabled (off). Guide: WebGL Fingerprinting.
--bot-config-webgpu=profile: WebGPU: profile (use profile), real (system), disabled (off). Guide: WebGPU Fingerprint Protection.
--bot-config-noise-webgl-image: WebGL image noise: true, false. Guide: WebGL Fingerprinting.
--bot-config-noise-canvas: Canvas fingerprint noise: true, false. Guide: Canvas Fingerprinting.
--bot-config-noise-audio-context: Audio context noise: true, false. Guide: Audio Fingerprinting.
--bot-config-noise-client-rects: Client rects noise: true, false. Guide: Font Fingerprinting.
--bot-config-noise-text-rects: Text rects noise: true, false. Guide: Font Fingerprinting.
--bot-config-speech-voices=profile: Speech voices: profile (profile-backed), real (system). Guide: Speech Synthesis.
--bot-config-media-devices=profile: Media devices: profile (profile-backed devices), real (system devices). Guide: Media Devices Privacy.
--bot-config-media-types=expand: Media types: expand (default), profile, real. Guide: MIME and Codec.
--bot-config-webrtc=profile: WebRTC: profile (use profile), real (native), disabled (off). Guide: WebRTC Leak Prevention.
Behavior & Protection Toggles
Runtime toggles that don’t rely on profile configs but still override behavior at launch.
--bot-disable-debugger: Ignore JavaScriptdebuggerstatements to avoid pauses. Guide: Automation Consistency.
--bot-mobile-force-touch: Force touch events on/off for mobile device simulation. Guide: Device Emulation.
--bot-disable-console-message(ENT Tier1): Suppress console output forwarded through automation protocols. Default: true. Guide: Console Suppression.
--bot-inject-random-history(PRO): Add profile history. Acceptstrue(random 2-7 entries), a number for a precise count, orfalseto disable. Guide: History Seeding.
--bot-enable-variations-in-context(ENT Tier2): IncludeX-Client-Dataheaders in incognito BrowserContexts. Disabled by default. Guide: Incognito Fingerprinting.
--bot-always-active(PRO, default true): Keep windows and tabs active when unfocused. Guide: Active Window.
--bot-webrtc-ice=google(ENT Tier1): Configure ICE endpoints with a preset (google) orcustom:stun:...,turn:.... Guide: WebRTC Leak Prevention.
--bot-noise-seed(ENT Tier2): Integer seed (1-UINT32_MAX) for reproducible Canvas, WebGL, WebGPU, text, ClientRect, and audio protection.0keeps profile defaults. Guide: Noise Seed Reproducibility.
--bot-fps(ENT Tier2): Control frame rate behavior. Acceptsprofile,real, or a number such as60. Guide: FPS Control.
--bot-video-fps=<actual>[:<reported>](ENT Tier2): Control video playback cadence separately from media FPS reporting on profiles with Video FPS Control enabled. Examples:1,1:30,1:real. Guide: FPS Control.
--bot-js-heap-size-limit=profile|real|<bytes>: Control the JavaScript heap size limit policy. Guide: Storage and Memory.
--bot-storage-quota=profile|real|<bytes>: Control the storage quota policy. Guide: Storage and Memory.
--bot-time-scale(ENT Tier2): Float below1.0for timing scale policy. Guide: Performance Fingerprinting.
--bot-time-seed(ENT Tier2): Integer seed (1-UINT32_MAX) for reproducible execution timing policy.0disables the feature. Guide: Performance Fingerprinting.
--bot-stack-seed(ENT Tier2): Useprofile,real, or a positive integer seed for stack depth policy across main thread, Worker, and WASM contexts. Guide: Stack Depth.
--bot-network-info-override: Enable profile-defined network information values and corresponding Client Hints. Disabled by default. Guide: Navigator Properties.
--bot-gpu-emulation(ENT Tier2, defaulttrue): Acceptsfalse,true, orpriority. Guide: Linux GPU Backend.
Mirror: Distributed Privacy Consistency (ENT Tier3)
Run one controller and multiple clients for synchronized cross-platform validation.
Key flags:
--bot-mirror-controller-endpoint=host:port- Launch as controller. Guide: Mirror Distributed.
--bot-mirror-client-endpoint=host:port- Launch as client. Guide: Mirror Distributed.
Setup: Mirror Distributed | Mirror tool
Usage Examples
For multi-instance, proxy, identity, mobile, media, and deployment commands, use CLI Recipes. The reference keeps one minimal launch example:
Minimal launch with proxy
chromium-browser \
--bot-profile="/absolute/path/to/profile.enc" \
--bot-title="My Session" \
--proxy-server=http://myuser:mypass@proxy.example.com:8080 \
--user-data-dir="/tmp/botbrowser-session" \
--remote-debugging-port=9222Related Documentation
- Guides Index - Setup and troubleshooting by workflow
- CLI Recipes - Scenario-based launch commands
- Profile Configuration Guide - Configure browser behavior via profiles
- Per-Context Fingerprint - Independent fingerprint per BrowserContext
- Main README - General usage and standard Chromium flags
- Examples - Playwright and Puppeteer integration examples
- Docker Deployment - Container deployment guides
Standard Chromium flags are listed here only when they directly affect a BotBrowser workflow, such as
--disable-quicand--proxy-pac-url. For the full Chromium switch catalog, see the Chromium command line documentation.
Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.