BrowserBox 03 Getting started
Fast Start
In this chapter
3.1 Standard local workflow #
bbx stop
bbx setup -p 8888
bbx startWhen you run bbx setup -p 8888, port 8888 becomes the main BrowserBox service port.
Related service ports are derived from the main port:
audio: main port - 2
docs: main port - 1
devtools: main port + 1
BrowserBox writes the current login link to:
~/.config/dosaygo/bbpro/login.link3.2 Core commands #
| Command | Purpose |
|---|---|
| bbx setup | Configure port, hostname, token, zeta mode, and backend mode. |
| bbx start | Start BrowserBox for the current user. --port and --hostname change and save the address (Section 7.3). |
| bbx stop | Stop BrowserBox for the current user. |
| bbx restart | Stop and relaunch BrowserBox using the connection type it was last started with. |
| bbx status | Check whether BrowserBox is reachable and running. --json prints a machine-readable result. |
| bbx logs | View BrowserBox logs. |
| bbx certify | Validate the current license and reserve a seat when applicable. |
| bbx vacancy | Show total, occupied, vacant, leased, and reserved seat counts, plus any local reservation metadata on the machine. |
| bbx update | Update BrowserBox to the latest or a specific release (Section 2.3). |
| bbx use-chrome | Install and select a specific Chrome version. |
| bbx gui | Install and open the BrowserBox desktop app (Section 3.3). |
| bbx policy | Inspect, validate, and set browsing policy (Section 5.10). |
| bbx fleet | Allocate and release clean-slate sessions from a Linux user pool (Section 11). |
| bbx ng-config | Print, validate, or atomically apply the four-service nginx facade configuration. |
| bbx ng-run | Run the nginx-oriented workflow. |
| bbx tor-run | Run BrowserBox with Tor integration. |
| bbx zt-run | Run BrowserBox on a ZeroTier network. |
| bbx cf-run | Run BrowserBox through a Cloudflare tunnel. |
| bbx uninstall | Remove BrowserBox, including the desktop app. |
Each *-run command also has a *-start spelling (for example bbx cf-start); the two are equivalent. bbx --help lists the commands, and bbx --help-json prints the complete command catalogue, including every flag, as JSON.
bbx logs displays the BrowserBox service list. To tail the main service directly, run:
browserbox pm2 logs bb-main --lines 50The browserbox pm2 command owns process-manager operations. Do not pass pm2 to bbpro; bbpro expects its first argument to be an environment-file path.
3.3 Desktop app (bbx gui, beta) #
BrowserBox includes a desktop app for people who prefer buttons to the command line. It is carried inside the BrowserBox binary, so there is nothing separate to download:
bbx gui # install if needed, then open
bbx gui --reinstall # reinstall the app from the current binaryThe first run installs the app for the current user and prints where it lives, so it can be pinned: ~/Applications/BrowserBox.app on macOS, a browserbox.desktop launcher on Linux, and a BrowserBox Start-menu shortcut on Windows (bbx gui -Reinstall in PowerShell). On Linux, run it from a desktop session; it needs a display.
The app is a front end to the same bbx commands described in this guide. Every action shows the exact command it will run. It has five tabs:
| Tab | What it does |
|---|---|
| Session | Shows whether BrowserBox is running and how it is reachable. Start, open, restart, or stop it, and copy the login link. The token itself is never displayed. |
| Connection | Choose how BrowserBox is reached: Direct, Cloudflare, ZeroTier, Tor, Nginx, or Legacy (Windows 9x mode), then launch it. |
| Fleet | A dashboard for a Fleet seat pool: capacity, public-route health, per-seat status, and pool actions such as new session, doctor, reconcile, and apply routes. Linux only; disabled on macOS and Windows. |
| Policy | View the effective browsing policy, validate it, check an action, or install or reset a policy file. |
| All commands | A searchable catalogue of every bbx command with a form for its options. |
Software Update… in the File menu runs bbx update. The desktop app is in beta; the bbx command line remains the complete, supported interface.
3.4 Automation and machine-readable output #
bbx keeps actionable results on standard output and informational messages (progress, update checks, policy footers) on standard error, so scripts can capture results cleanly.
bbx status --json # one JSON document on stdout
bbx status --out /path/status.json # same, written atomically to a file
bbx --help-json # full command catalogue (schema bbx.help/1)
bbx --output-log /path/new.log -- start # send a command's output to a new filebbx status --json reports running, hostname, scheme, main_port, version, the audio state, and the active connection type. It never includes the login token. --output-log takes an absolute path, writes both output streams to that new owner-only file, and refuses to overwrite an existing file.
Set BBX_PROGRESS_EVENTS=1 to have long-running commands print one-line progress markers such as @bbx-progress ready and failure markers such as @bbx-failure license-refused. These are intended for wrappers and orchestration tools that need to show progress without parsing human-readable output.