13 Reference

Customer-Relevant Environment Variables

Customer guide · v20.1.8 · October 12, 2026

In this chapter

Core customer-facing variables
Examples

13.1 Core customer-facing variables #

The native BrowserBox runtime accepts the established user.env and test.env contract. Unknown variables are ignored, and punctuation in string-valued settings is treated as data rather than evaluated as program text. A small number of legacy Node-specific tuning names remain accepted as compatibility inputs so an existing environment file does not prevent an upgrade; their native behavior is called out explicitly below.

Name	Default	Meaning
`ALLOWED_EMBEDDING_ORIGINS`	unset	Space-separated allowlist of parent origins permitted to embed BrowserBox.
BBX_HTTP_ONLY	unset	Forces HTTP-only mode, skips direct DNS ownership checks, and skips HTTPS certificate generation. Useful behind a reverse proxy.
BBX_EXTERNAL_TLS	unset	Treats the frontend as secure when TLS is terminated upstream. When exported before installation, also skips installer-time BrowserBox certificate generation.
BBX_NO_HSTS	unset	Explicitly set to `true` (also accepts `1`, `yes`, or `on`) to omit only the HTTP Strict Transport Security header. This is independent of Tor and TLS mode; use it for a corporate ingress that cannot accept HSTS. HTTPS, certificate validation, CSP, and every other security header remain enabled.
BBX_SSLCERTS_DIR	unset	Directory containing customer-managed TLS files such as `fullchain.pem` and `privkey.pem`. Respected by `setup`, `ng-run`, `ng-config`, and `--for` mode.
BBX_SHUTDOWN_IDLE_MS	2700000	Main no-client shutdown from runtime startup and after the last client disconnects.
`BBX_MINIMAL_MODE_IDLE_MS`	120000	Minimal-mode idle shutdown fallback.
`FLEET_REAP_INTERVAL_SECS`	5	Delay between foreground `fleet monitor` recovery passes.
`FLEET_REAP_GRACE_SECS`	15	Required continuously-down window before monitor or one-shot reaping releases an allocation.
`FLEET_ACQUIRE_REAP_GRACE_SECS`	2	Confirmation window for acquire-time recovery of allocations already observed fully down.
`FLEET_STALE_RESERVE_SECS`	900	Age after which a fully down transitional allocation is eligible for monitor/reap recovery.
`FLEET_MONITOR_MAX_BACKOFF_SECS`	300	Maximum retry delay after repeated monitor-pass failures.
`FLEET_MONITOR_FAILURE_DETAIL_LIMIT`	10	Maximum per-allocation automatic-release failure lines in one pass; additional failures are summarized.
BBX_HOME_PAGE	unset	Preferred home page URL.
`BBX_DEFAULT_HOME_PAGE`	https://duckduckgo.com	Fallback home page URL.
BBX_CUSTOM_CURSOR	unset	Path to a local image file used as the remote cursor image.
BBX_HOSTNAME	system hostname or prompt	Hostname used for BrowserBox setup.
DOMAIN	unset	Explicit route-domain override for network-oriented commands such as `ng-run`. Use only when overriding the saved setup domain.
`BBX_UI_THEME_OVERRIDE`	unset	Default login UI theme when a supported theme is requested.
`BBX_SHOW_STREAMING_STATS_OVERLAY`	unset	Displays the live streaming stats overlay in the BrowserBox client UI.
BBX_MAX_CONNECTIONS	3	Per-session client connection cap, from 1 through 5. Clients admitted with the same connector co-browse the same remote browser. Larger positive legacy values are safely capped at 5.
BBX_MAX_TABS	20	Maximum concurrent page tabs per BrowserBox session. Applies to both user-initiated tab creation and browser-initiated popups (e.g. `window.open` or links with `target="_blank"`). When a client is connected at the time a popup is blocked, a notification appears in the client UI. Tabs that would exceed the cap at service startup are closed silently, with no client notification. Set this persistently in `user.env` (see Section 7.4) so it survives `bbx setup` regeneration.
BBX_CLEAN_SLATE	unset	When `true`, clears the browser user-data directory at startup. Useful for ephemeral deployments that need a fresh profile every launch.
BBX_MINIMAL_MODE	unset	Runs BrowserBox with only the main service (no audio, docs, or devtools sidecars). Useful for constrained environments or single-purpose kiosks.
BBX_DISABLE_WEBRTC	unset	When `true`, disables WebRTC entirely and forces WebSocket-only transport.
`BBX_DISABLE_WEBRTC_RACING`	false	Native BrowserBox starts with WebRTC and retains WebSocket fallback, but normally sends one sparse same-frame sample every 60 published frames so the client can compare both paths. Set to `true` to disable only those samples and learned path switching; it does not disable WebRTC.
BBX_AD_BLOCK	true	Master switch for ad-specific blocking. Set to `false` and restart BrowserBox to disable both BrowserBox request-level ad blocking and Chrome’s native ad filter. Policy enforcement, authentication, and PDF handling may still use request interception without blocking ads.
`BBX_NATIVE_AD_BLOCK`	false	Adds Chrome’s native subresource ad filter when `true`. Has no effect when `BBX_AD_BLOCK=false`.
BBX_ADAPTIVE_IMAGERY	accepted	Compatibility input. Native v20 uses the measured fixed JPEG-80, every-frame capture profile with ACK pacing and bounded coalescing; this variable does not change that native profile. It remains safe to leave in an environment migrated from the earlier Node backend.
BBX_LOW_END_MODE	true	When `true`, forces Chrome low-end-device behavior. Set to `false` on adequately provisioned performance hosts; validate constrained deployments before changing it.
BBX_NO_AUDIO	unset	When `true`, does not start the audio service and tells the client not to retry audio setup. Use only when remote audio is not required.
BBX_NETWORK_DOMAIN	false	Controls fine-grained CDP Network tracking. Disabled by default: BrowserBox synthesizes page-loading progress from page lifecycle events, avoiding a high-volume internal event stream on network-heavy applications. Set to `true` to restore fine-grained network telemetry. Navigation to local files and browser-internal pages remains blocked in both modes.
BBX_OOPIF	true	Attaches BrowserBox to Chrome’s separately rendered cross-site iframe targets so cursor and supported page integrations work inside OOPIFs. Set to `false` and restart only as a temporary compatibility fallback.
`BBX_CDP_PERMESSAGE_DEFLATE`	accepted	Legacy Node-WebSocket compatibility input. Native v20 uses its own bounded CDP transport and does not apply this setting.
`BBX_CDP_SKIP_UTF8_VALIDATION`	accepted	Legacy Node-WebSocket compatibility input. Native v20 performs its own bounded message validation and does not apply this setting.
`BBX_CDP_ALLOW_SYNCHRONOUS_EVENTS`	accepted	Legacy Node event-loop compatibility input. Native v20 has no Node event-loop delivery mode, so this setting has no native effect.
BBX_GPU	unset	On supported bare-metal Linux hosts, `true` enables the hardware-GPU profile, including explicit headless GPU enablement, native EGL ANGLE, and GPU rasterization.
`BBX_SUPPORT_CONTACT`	support@dosaygo.com	Email address or URL shown as the support contact on built-in blocked pages (Section 4.8).
`BBX_STATUS_PAGES_DIR`	unset	Additional directory of customer blocked-page files, searched first (Section 4.8).
BBX_NO_UPDATE	unset	Disables automatic and explicit updates (Section 2.3).
BBX_NO_CDN	unset	When `1`, downloads release files from GitHub only, bypassing the release mirror.
BBX_ASSET_BASE	https://dl.getbrowserbox.com	Base URL of the release mirror. Point it at your own mirror laid out as `<base>/<tag>/<file>`.
`BBX_PROGRESS_EVENTS`	unset	When `1`, long-running commands print `@bbx-progress` and `@bbx-failure` markers (Section 3.4).
`BBX_DEBUG_LICENSE`	unset	When `true`, logs routine licensing requests for support diagnostics.
LICENSE_KEY	unset	Your BrowserBox product key. Can be set in the environment, passed to `bbx certify`, or persisted in `test.env` after first certification.
`HTTP_PROXY / HTTPS_PROXY http_proxy / https_proxy`	unset	Standard forward-proxy URLs. BrowserBox runtime HTTPS calls, including continuous licence validation, honour these values.
`NO_PROXY no_proxy`	unset	Standard comma-separated proxy exclusions. Include loopback and internal domains/ranges even though BrowserBox’s own loopback health checks bypass proxies explicitly.
NODE_EXTRA_CA_CERTS	unset	PEM bundle containing additional trusted CAs, commonly the corporate TLS-inspection CA. Set before `bbx start`; never disable TLS verification to accommodate interception.

HSTS opt-out scope. BrowserBox emits HSTS by default. BBX_NO_HSTS does not enable HTTP, weaken certificate checks, or change Tor behavior; it only omits Strict-Transport-Security from BrowserBox responses. A browser that previously cached HSTS for the hostname may retain that state until its cached policy expires or is cleared, so set this before first production access on an affected corporate hostname.

13.2 Examples #

export ALLOWED_EMBEDDING_ORIGINS="https://app.example.com https://localhost:*"
export BBX_HTTP_ONLY=1
export BBX_EXTERNAL_TLS=true
export BBX_SSLCERTS_DIR="/path/to/certs"
export BBX_HOME_PAGE="https://intranet.example.com"
export BBX_CUSTOM_CURSOR="/absolute/path/to/cursor.png"
export BBX_SHUTDOWN_IDLE_MS=7200000
export BBX_UI_THEME_OVERRIDE=dark
export BBX_SHOW_STREAMING_STATS_OVERLAY=true
export BBX_MAX_CONNECTIONS=5
export BBX_MAX_TABS=24
bbx setup
bbx start

Cross-user execution:

# Run as operator, services execute as bbxruntime
bbx setup --port 9090 --hostname app.example.com -z --for bbxruntime
bbx ng-run --for bbxruntime
bbx stop --for bbxruntime

Certificate override with cross-user execution:

export BBX_SSLCERTS_DIR="/opt/shared-certs"
bbx ng-run --for bbxruntime