Skip to content

PROFILE_CONFIGS.md

Latest commit

 

History

History
223 lines (176 loc) · 10.8 KB

PROFILE_CONFIGS.md

File metadata and controls

223 lines (176 loc) · 10.8 KB
Raw

BotBrowser Profile Configuration

This is the field reference for configurable subscription profile packages. Profile package authoring requires ENT Tier1; individual fields keep the availability listed below. Public legacy .enc files are read-only. For per-session changes, use the CLI Flag Directory.

Table of Contents

Configuration Priority

  1. CLI flags
  2. Profile configs
  3. Profile defaults

CLI flags have the highest priority. Keep profile defaults unless a persistent override is required.

Apply Configuration

When a supplied profile package permits configuration, place configs before the key block:

{
  "configs": {
    "locale": "auto"
  },
  "key": { /* ... */ },
  "version": { /* ... */ },
  "profile": { /* ... */ }
}

Do not modify public legacy .enc files. BotBrowser accepts profile input from a file; shell process substitution and piped JSON are not supported. Use an absolute path when launching with --bot-profile.

Configurable Fields

Availability applies to custom values or behavior where noted. Core fields are available with the base profile capability.

Identity and Locale

Field Values Default
languages auto, or a language list such as en-US,en (ENT Tier1 custom) auto
locale auto, or a locale such as en-US (ENT Tier1 custom) auto
timezone auto, real, or an IANA timezone (ENT Tier1 custom) auto
location auto, real, or coordinates (ENT Tier1 custom) auto
browserBrand chromium, chrome, edge, brave, opera (ENT Tier2); webview (ENT Tier3) chrome
brandFullVersion Browser-family full version (ENT Tier2) Empty
uaFullVersion Chromium full version matching the active major (ENT Tier2) Empty
colorScheme light, dark light
disableDeviceScaleFactorOnGUI true, false false

Timezone, locale, and languages derive from the proxy IP when set to auto.

Session and Behavior

Field Values Default
disableConsoleMessage true, false (ENT Tier1) true
injectRandomHistory true, false, or a history count (PRO) false
enableVariationsInContext true, false (ENT Tier2) false
disableDebugger true, false true
keyboard profile, real profile
alwaysActive true, false (PRO) true
mobileForceTouch true, false false
portProtection true, false (PRO) false

Proxy and Requests

Field Values Default
proxy.server scheme://username:password@hostname:port Empty
proxy.ip Proxy public IP (ENT Tier1) Empty
webrtcICE google, or custom:stun:...,turn:... (ENT Tier1) google
customHeaders Header object (PRO) {}

Use --proxy-server for per-session proxy credentials. For SOCKS5 UDP and QUIC behavior, see UDP over SOCKS5.

Window and Screen

Field Values Default
window profile, real, WxH, or a window object Mode-dependent
screen profile, real, WxH, or a screen object Mode-dependent

Headless and mobile profiles default to profile-backed dimensions. Desktop headful sessions default to real dimensions. Configure window and screen together when overriding either value.

Rendering and Media

Field Values Default
webrtc profile, real, disabled profile
fonts profile, expand, real profile
webgl profile, real, disabled profile
webgpu profile, real, disabled profile
mediaDevices profile, real profile
speechVoices profile, real profile
mediaTypes expand, profile, real expand

Noise and Performance

Field Values Default
noiseCanvas true, false true
noiseWebglImage true, false true
noiseAudioContext true, false true
noiseClientRects true, false false
noiseTextRects true, false false
fps profile, real, or a number (ENT Tier2) profile
timeScale 1.0, or a number greater than 0 and below 1 (ENT Tier2) 1.0
noiseSeed 0, or an integer from 1 to UINT32_MAX (ENT Tier2) Profile default
timeSeed 0, or an integer from 1 to UINT32_MAX (ENT Tier2) 0
stackSeed profile, real, or a positive integer (ENT Tier2) real
networkInfoOverride true, false, profile, or JSON policy false

For a custom policy, use a JSON string so the profile remains valid JSON:

{
  "configs": {
    "networkInfoOverride": "{\"type\":\"profile\",\"rtt\":\"host\",\"downlink\":2.5}"
  }
}

Video playback cadence is a CLI-only policy. See --bot-video-fps. JavaScript heap and storage quota policies are also configured at runtime through --bot-js-heap-size-limit and --bot-storage-quota.

Custom User-Agent (ENT Tier3)

Use these fields together with a --user-agent template:

Field Values Default
platform Windows, Android, macOS, Linux Profile value
platformVersion OS version Profile value
model Device model Profile value
architecture x86, arm, arm64 Profile value
bitness 32, 64 Profile value
mobile true, false Profile value

The browser keeps the User-Agent string, Client Hints, main thread, workers, and request headers aligned with these values.

WebKit-Family Profiles (ENT Tier4)

Use the supplied premium profile as the source of browser-family identity. Do not assemble WebKit-family behavior from standalone configs fields. Limit overrides to session-specific values such as proxy, locale, and routing. See WebKit-Family Profile Consistency.

Example Profile configs Block

{
  "configs": {
    "languages": "auto",
    "locale": "auto",
    "timezone": "auto",
    "location": "auto",
    "colorScheme": "light",
    "proxy": {
      "server": "socks5://username:password@proxy.example.com:1080",
      "ip": "203.0.113.1"
    },
    "window": "profile",
    "screen": "profile",
    "webrtc": "profile",
    "fonts": "profile",
    "webgl": "profile",
    "webgpu": "profile",
    "mediaTypes": "expand",
    "noiseCanvas": true,
    "noiseWebglImage": true,
    "noiseAudioContext": true
  },
  "key": { /* ... */ },
  "version": { /* ... */ },
  "profile": { /* ... */ }
}

Notes

  • The profile package and BotBrowser binary must use the same major version.
  • CLI flags override profile configs.
  • Omitted fields keep the profile default.
  • Keep browser-family and version values aligned with the active profile and Chromium major.
  • Use auto for geographic fields unless the session requires an explicit value.
  • Keep proxy credentials outside shared profile packages when they vary by session.

Related Documentation

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