Installation and Customer Resources

2.1 Official install entrypoints #

BrowserBox installation guidance is published at https://browserbox.io. The current public install entrypoints are:

• macOS and Linux: curl -fsSL https://browserbox.io/install.sh | bash

• Windows: irm https://browserbox.io/install.ps1 | iex

The Unix installer requires unzip and installs it when it is missing. This guide documents the bash bbx command on macOS and Linux. Windows is covered in Section 2.2.

2.2 Windows #

The Windows PowerShell bbx supports the everyday commands: setup, start, stop, restart, status (including --json), logs, certify, activate, vacancy, update, use-chrome, uninstall, gui, and the connection commands cf-start, tor-start, zt-start, ng-start, ng-config, and win9x-start. Both PowerShell-style parameters (for example -Port 8888) and the Unix-style --port 8888 forms are accepted.

Windows runs one BrowserBox instance per machine. The following are Linux- or macOS-only and are refused on Windows with an unknown or unsupported command message before BrowserBox starts: fleet, start-as, stop-user, and --for. Remote audio is not available on Windows; bbx status reports audio as disabled.

Windows-specific behavior worth knowing:

• Cloudflare, Tor, and nginx tools are downloaded on first use into %LOCALAPPDATA%\browserbox\tools. Installing ZeroTier One requires an Administrator prompt.

• bbx ng-start serves a single origin on port 443; zeta mode is not used on Windows.

• bbx stop also stops the Cloudflare, Tor, and nginx processes that bbx started.

• Services started over SSH keep running after the SSH session disconnects.

• bbx uninstall removes BrowserBox but keeps your configuration and certificates.

2.3 Updates #

bbx update and the background update check download release files from the BrowserBox release mirror at https://dl.getbrowserbox.com, and fall back to GitHub automatically if the mirror is slow or unreachable. Every file is verified against the signed release manifest whichever source it came from; a file from the mirror that fails verification is fetched again from GitHub. The first-time installers download from GitHub.

Updates are applied in two phases. A new release is downloaded and verified in the background, then installed at the start of your next bbx command, which re-runs on the new version. Installed executables are replaced atomically, so a command that is already running never sees a partially written file.

Allow dl.getbrowserbox.com, github.com, and api.github.com on TCP 443 for updates, or set BBX_NO_UPDATE=true and upgrade through your own change process.

2.4 Suggested first run #

After installation, the normal customer workflow is:

bbx certify YOUR_KEY
bbx setup -p 8888
bbx start

If you are evaluating BrowserBox, obtain your license through https://browserbox.io. Commercial licensing and evaluation paths are surfaced there, and the site links through to the current purchase flow.

2.5 Prerequisites #

BrowserBox requires a Chrome-family browser (Google Chrome or Chromium) installed on the host machine. If Chrome is not found, runtime commands (start, run, ng-run, etc.) will refuse to launch and print:

Chrome/Chromium is not installed.
BrowserBox requires a Chrome-family browser to run.
Install it with:  browserbox --full-install <hostname> <email>

2.6 Network requirements #

BrowserBox validates its licence continuously while running (every 331 seconds), not only at activation time. Each licensing service has an independent fallback, so the host must be able to reach all four of the following endpoints over TCP 443:

• https://license.dosaygo.com and its fallback https://license2.dosaygo.com

• https://master.dosaygo.com and its fallback https://master2.dosaygo.com

Every request goes to the primary first. BrowserBox uses the fallback only when the primary cannot be reached (DNS, connection, TLS, or timeout failures, or a gateway error), so a licence remains usable during a primary outage. Validation is identical on either endpoint.

These endpoints may be reached directly or through a configured HTTP forward proxy. BrowserBox still performs the complete signed ticket, seat, and challenge-response validation when a proxy is used; proxy routing does not disable or weaken licence enforcement. If neither the primary nor the fallback endpoints can be reached by either route, the main service stops and restarts repeatedly, and bbx logs records errors such as:

[PKI] Error fetching public key: Fetch to https://license.dosaygo.com/keys/root timed out
Error: Local certificate validation failed.

On networks where egress is restricted, permit all four destinations before deploying. Routine licensing detail is not logged by default; set BBX_DEBUG_LICENSE=true and restart when support asks for licensing diagnostics. If direct egress is prohibited, configure the forward proxy as described below.

2.7 Operating behind an HTTP forward proxy #

BrowserBox honours the standard upper- and lower-case proxy variables: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and their lower-case forms. NO_PROXY and no_proxy exclude destinations from proxy routing. These are operating-system conventions, not BrowserBox-specific variables.

Set the proxy variables in the environment that starts BrowserBox, or persist them in user.env (Section 7.4). Also set both forms of NO_PROXY so loopback and internal traffic from BrowserBox and its dependencies stays local:

export http_proxy="http://proxy.example.com:3128"
export https_proxy="$http_proxy"
export no_proxy="localhost,127.0.0.1,::1,10.0.0.0/8,.internal.example.com"
export NO_PROXY="$no_proxy"

BrowserBox’s own loopback health checks explicitly bypass forward proxies. A complete NO_PROXY value remains recommended because package managers, Chrome, and other host tools may independently honour the same proxy environment.

The service orchestrator propagates the active BBX_*, proxy, certificate-authority, and sound-session variables to every BrowserBox service and its restart guardian. Proxy credentials do not need a second BrowserBox-specific configuration surface.

If the corporate proxy performs TLS inspection, add its trusted CA before starting BrowserBox rather than disabling certificate validation:

export NODE_EXTRA_CA_CERTS="/etc/pki/ca-trust/source/anchors/corporate-proxy.pem"
bbx start

NODE_EXTRA_CA_CERTS is read when the Node.js runtime starts, so restart BrowserBox after changing it.

2.8 Audio prerequisites on headless hosts #

The audio service captures sound from a PulseAudio or PipeWire server running in the service user’s session. On a headless server that session does not exist by default. BrowserBox checks this dependency during startup: the main service continues running, while bbx status reports audio as Ready, Degraded, or Disabled with an actionable detail.

On systems using PipeWire’s PulseAudio compatibility service, BrowserBox installs a native pipewire-pulse drop-in that creates the channel playback sink, the rtp capture sink, and the loopback between them. bbx setup selects channel for Chrome, while the audio service captures rtp.monitor. This configuration is capability-detected: systems using native PulseAudio keep the established default.pa path unchanged. The drop-in is installed by both a full installation and the command-install step run automatically by bbx update.

Ensure the service user has a durable session:

sudo loginctl enable-linger bbuser

Start BrowserBox as that user, from that user’s own login session. Then verify:

pactl info                      # should print a Server String
pactl list short sinks          # at least one sink present
pactl list short sources        # should include rtp.monitor

While a page is playing sound, pactl list short sink-inputs should show an active stream. See Section 7.6.3 if it does not.

2.9 Selecting or pinning Chrome #

BrowserBox normally discovers a compatible Chrome-family browser automatically. When support recommends a specific Chrome major for compatibility testing, use:

bbx use-chrome 149

The command resolves and installs the requested Chrome-for-Testing major, then persists the resulting CHROME_PATH in /̃.config/dosaygo/bbpro/user.env. The selection therefore survives bbx setup and service restarts. You may also supply an executable path directly, for example bbx use-chrome /opt/google/chrome/chrome.

Pinning is a compatibility or rollback measure, not the first response to every startup failure. Before changing Chrome, run bbx logs and check for integrity, configuration, license, port, or certificate errors. To return to automatic browser discovery, remove the CHROME_PATH line from user.env and run bbx restart.

2.10 Full machine setup (--full-install) #

On a fresh server without Chrome or other dependencies:

browserbox --full-install <hostname> <email>

• <hostname> — the domain or IP address (e.g. localhost, bbx.example.com, 198.51.100.42).

• <email> — email used for BrowserBox terms acceptance and, when applicable, public-certificate issuance.

This installs Chrome, Node.js, TLS tooling, and the other OS-level dependencies BrowserBox needs. For non-interactive installs, the preferred environment variables are BBX_INSTALL_HOSTNAME and BBX_INSTALL_EMAIL. Legacy aliases BBX_HOSTNAME, BBX_EMAIL, and EMAIL are still accepted. If you run the standalone installer as root in a non-interactive environment, also set BBX_INSTALL_USER to the non-root account that should own the installation.

For non-interactive (scripted) installs, set BBX_TEST_AGREEMENT=true to auto-agree to the license agreement:

export BBX_TEST_AGREEMENT=true
export BBX_INSTALL_HOSTNAME="bbx.example.com"
export BBX_INSTALL_EMAIL="you@example.com"
browserbox --full-install "$BBX_INSTALL_HOSTNAME" "$BBX_INSTALL_EMAIL"

2.11 Support and public references #

• Product site and license purchasing: https://browserbox.io

• Public GitHub repository: https://github.com/BrowserBox/BrowserBox

• Support email: support@dosaygo.com