Customer Customization Surfaces

4.1 Login-link URL parameters #

BrowserBox generates login links with query parameters that affect customer-visible behavior.

For one starting page, the simplest value is a bare URL such as https://example.com. A JSON string such as "https://example.com" is also accepted. To open multiple starting tabs, use a JSON array such as ["https://example.com","https://docs.example.com"]. URL-encode the complete value before appending it as url=...; do not encode or modify the login token itself.

When reopening a login link for a running session, the url= parameter will intelligently reuse and navigate an existing suitable tab rather than creating a duplicate tab. This makes it fully compatible with single-tab topologies such as BBX_MAX_TABS=1.

When ui= is explicitly present, BrowserBox treats that as embedder-owned configuration and locks the user toggle accordingly.

4.2 Homepage selection #

Use either of these variables:

export BBX_HOME_PAGE="https://intranet.example.com"
# or
export BBX_DEFAULT_HOME_PAGE="https://intranet.example.com"

By default, BrowserBox asks Chrome to restore tabs from the previous browser session. If no usable page tab is restored, BrowserBox opens the configured home page. To preserve the browser profile while always beginning with the home page instead of restored tabs, set:

export BBX_RESTORE_LAST_SESSION=false
export BBX_HOME_PAGE="https://intranet.example.com"

4.3 Declared startup tabs #

Use BBX_STARTUP_TABS to declare the exact tab topology for the initial BrowserBox start. The value is a non-empty JSON array of absolute URLs:

export BBX_STARTUP_TABS='["https://intranet.example.com"]'

This starts BrowserBox with exactly one page tab without restoring tabs from the previous Chrome session. It preserves cookies, local storage, preferences, and other browser-profile data. It does not restrict later navigation or prevent the user from opening more tabs.

Multiple initial tabs are also supported:

export BBX_STARTUP_TABS='["https://intranet.example.com", "https://docs.example.com"]'

The number of declared startup tabs must not exceed BBX_MAX_TABS. Navigation policy still applies to every declared URL. When set, BBX_STARTUP_TABS takes precedence over BBX_HOME_PAGE and BBX_RESTORE_LAST_SESSION for initial startup.

The value must be a valid http: or https: URL. Invalid values fall back to https://duckduckgo.com.

4.4 Cross-origin iframe compatibility (OOPIF) #

BrowserBox enables out-of-process iframe (OOPIF) support by default. Modern Chrome may place a cross-site iframe in a separate renderer process; BrowserBox attaches to that target so cursor support, page integrations, and supported injected capabilities continue to work inside the frame. This also applies recursively to nested cross-site frames.

The same attachment policy safely releases dedicated and shared Web Workers without treating them as tabs. Worker-dependent applications, including PDF.js viewers, therefore continue to run while OOPIF support remains enabled. If a worker-dependent page stalls on an older BrowserBox release, upgrade before disabling OOPIF support permanently.

If a site exhibits a compatibility or stability problem after an upgrade, an administrator can temporarily return to the previous behavior:

export BBX_OOPIF=false
bbx restart

For a persistent setting, add BBX_OOPIF=false to ~/.config/dosaygo/bbpro/user.env, then restart BrowserBox. Disabling OOPIF support means BrowserBox will no longer attach to separately rendered cross-site iframe targets, so BrowserBox-provided cursor and page integrations may not be available inside those frames. Include bbx logs output when reporting an OOPIF compatibility issue.

4.5 Printing #

BrowserBox handles printing as an explicit download intent rather than opening a printer attached to the BrowserBox host. When a page calls window.print(), the built-in Chrome PDF viewer requests printing, or the user selects Print from the BrowserBox context menu, BrowserBox asks for confirmation. After confirmation, BrowserBox creates or retrieves a PDF and presents the existing download-ready dialog. The user downloads that PDF and prints it with a local printer.

Printing requires downloads to be allowed by the active BrowserBox policy. A print request from a separately rendered OOPIF is captured in that target; a request from a same-process iframe produces the printable document for its owning page target.

4.6 Custom cursor #

export BBX_CUSTOM_CURSOR="/absolute/path/to/cursor.png"
bbx start

BrowserBox reads the local file at startup and uses it as the remote cursor image.

4.7 UI theme override #

export BBX_UI_THEME_OVERRIDE=dark
bbx start

This sets the default BrowserBox UI theme for the login flow. A login-link uiTheme= parameter can also request a theme when accepted by the server.

4.8 Blocked-page customization #

When BrowserBox refuses a navigation, it serves a page in place of the site. By default that page carries BrowserBox branding and directs the user to DOSAYGO support. Deployments that enforce their own allowlists will usually want the user directed to their own service desk instead.

4.8.1 Changing only the support contact #

If the built-in wording and layout are acceptable and only the contact details are wrong, set one variable:

export BBX_SUPPORT_CONTACT="servicedesk@example.com"
bbx restart

An email address is rendered as a mailto: link. A value beginning http://, https://, mailto:, or tel: is used as the link target as given, so a ticketing form may be used instead:

export BBX_SUPPORT_CONTACT="https://servicedesk.example.com/new-request"

This variable reaches the two built-in pages marked in the table in §4.8.2, and nothing else. In particular it has no effect on a page you install, because an installed page is served exactly as written. The two mechanisms are alternatives rather than layers: either BrowserBox composes the page and reads this variable, or it serves your file and does not. A page you install should carry your contact details in its own markup.

4.8.2 Replacing a page #

To replace a page entirely, install an HTML file named after the page id into a status-pages directory. Global pages are read from /etc/browserbox/status-pages/, which must be root-owned and world-readable; per-user pages are read from ~/.config/dosaygo/bbpro/status-pages/. A global page takes precedence, so a page installed by an administrator cannot be replaced by the account the browser session runs as. A directory named by BBX_STATUS_PAGES_DIR, when set, is searched before both and is subject to the same ownership checks as a per-user directory.

The final column indicates whether the built-in version of that page displays the support contact, and therefore whether BBX_SUPPORT_CONTACT changes it.

Deployments enforcing an allowlist through BrowserBox policy should customize blocked-policy.html. That is the page a user reaches when they attempt to browse outside the allowlist.

blocked-policy.html falls back to blocked.html. Installing blocked.html alone therefore changes both; install blocked-policy.html as well only when policy denials should read differently from ad blocking.

sudo install -d -o root -g root -m 0755 /etc/browserbox/status-pages
sudo install -o root -g root -m 0644 blocked-policy.html \
  /etc/browserbox/status-pages/blocked-policy.html

Changes take effect within a few seconds, on the next blocked navigation. No restart is required.

Login and authentication screens, and the pages shown while the remote browser is starting or after it has failed, are part of BrowserBox itself and are not customer-overridable.

4.8.3 Requirements an installed page must meet #

An installed page is used only if all of the following hold:

• it is a regular file, not a symbolic link

• it is not group-writable or world-writable

• it is owned by root for a global page, or by the account running BrowserBox for a per-user page

• the directory containing it meets the same ownership and permission requirements

• it is at most 256 KB

The most common installation error is copying the file as an ordinary user rather than as root. In /etc/browserbox/status-pages/, a file owned by any account other than root is ignored.

A file that fails any requirement is ignored, the built-in page is served in its place, and BrowserBox logs one line naming the file and the reason. A malformed or rejected page never changes whether a request is blocked, only what the user is told about it.

4.8.4 Authoring notes #

The file is served exactly as written. BrowserBox applies no template syntax and performs no substitution of any kind — BBX_SUPPORT_CONTACT included — so a static page cannot name the address that was refused. The built-in policy page shows the address and the policy reason code; an installed page replaces that with whatever it contains.

Blocked pages are served inside the remote browser, at the origin of the address that was refused, and reach the user as streamed canvas output. The user’s own browser does not parse the file. Three consequences follow:

• The file executes in the remote browser at that origin, and should be treated as trusted content. This is the reason for the ownership requirements above.

• mailto: and tel: links do reach the user. BrowserBox detects the external-protocol navigation, asks the user to confirm the request, and on approval opens the address on their own machine so their local mail client handles it. Write contact details as visible text as well, so they can be read and copied if the user declines the prompt.

• External stylesheets, fonts, and images are fetched by the remote browser and are subject to the same allowlist that produced the block. Inline CSS and embed images as data: URIs.

4.9 Idle shutdown after disconnect #

export BBX_SHUTDOWN_IDLE_MS=7200000
bbx start

This controls how long BrowserBox waits after all clients disconnect before shutting down.

If you run with BBX_MINIMAL_MODE="true" and do not set BBX_SHUTDOWN_IDLE_MS, BrowserBox uses BBX_MINIMAL_MODE_IDLE_MS as the fallback idle shutdown duration.