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.

Configuration Priority
Apply Configuration
Configurable Fields
Example
Notes

Configuration Priority

CLI flags
Profile configs
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.

For display-scale policy, use --bot-dpr at launch or when creating a browser context. It overrides the profile’s DPR policy; do not add a dpr field to configs. See Device Pixel Ratio Policy.

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.

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

For the public browser behavior and privacy context behind this guide, read Browser Automation CLI Recipes: Practical Command Examples.