13 Reference

Customer-Relevant Environment Variables

Customer guide · v19.3.1 · September 29, 2026

In this chapter

Core customer-facing variables
Examples

13.1 Core customer-facing variables #

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_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_SKIP_CERT_COPY	unset	Prevents BrowserBox-managed certificates from overwriting certificates in the configured certificate directory.
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. Clients admitted with the same connector co-browse the same remote browser.
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_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	true	Adapts screencast quality and frame cadence from measured streaming pressure. Leave enabled for the measured high-throughput profile.
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`	false	Controls compression on the trusted loopback Chrome DevTools WebSocket. Keep disabled to avoid compression CPU overhead.
`BBX_CDP_SKIP_UTF8_VALIDATION`	true	Skips redundant UTF-8 validation on trusted loopback CDP JSON messages. Set to `false` for compatibility diagnostics.
`BBX_CDP_ALLOW_SYNCHRONOUS_EVENTS`	true	Advanced tuning. Controls whether multiple CDP WebSocket messages may be delivered in a single event-loop turn. Setting `false` gives the Node event loop more room to breathe under heavy CDP load, at the cost of slightly higher per-message latency.
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.

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_SKIP_CERT_COPY=1
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=8
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