Fast Start

4.1 Standard local workflow #

bbx stop
bbx setup -p 8888
bbx start

When 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.link

4.2 Core commands #

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 supervised BrowserBox service logs. Process custody and restart behavior are internal runtime responsibilities; normal operation does not require a separate process-manager command.

4.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 binary

The 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 six tabs:

The Hyperscale tab is available directly; it does not require an experiment switch. See Section 14 for deployment setup and lifecycle commands.

Software Update… in the File menu runs bbx update. The desktop app is in beta; the bbx command line remains the complete, supported interface.

4.3.1 Session and Connection: start and share a browser #

Open Connection, choose the connection type, and fill in its address and options. Labels distinguish saved values, unsaved edits, CLI defaults, and required fields. Reload saved discards edits; Launch applies the form. The Session tab’s Start button uses that same selected connection. Changing a form alone does not launch a browser.

In Session, follow Activity while startup completes, then choose Open BrowserBox or Copy login link. A saved link and a reachable service are separate observations: a link can appear before startup verification finishes. Share the full login link only with intended users; it grants access to the session.

The screenshots below use the actual desktop renderer with example data. Hostnames, deployments and seat states are illustrative; available actions depend on the host platform and permissions.

Open a recent task or use View → Output window to inspect command output. Closing the app offers Close GUI only, Stop and close, and Keep open. Close GUI only leaves independent BrowserBox services running and is unavailable while the window owns a non-status command. Use Stop and close to end an owned foreground tunnel through the normal stop flow.

4.3.2 Fleet: manage a Linux session pool #

On a Linux Fleet host, open Fleet and use Refresh to read pool capacity, routing health and seat state. Select a seat to inspect its allocation. An active seat offers Open, Copy link, Check, and Release… when available; a free seat can start a session. New session allocates from the pool. Release ends that allocation and returns its seat to the pool.

Initialize… configures a pool; Doctor diagnoses it. Reconcile, Repair, Reap expired and Apply routes are administrative operations: read the proposed command and confirmation before proceeding. Privileged actions require the corresponding host permissions. Fleet is disabled on macOS and Windows.

4.3.3 Policy and All commands #

Open Policy to read the effective rules and their source locations, validate the policy, or check an action before applying a change. Installing or resetting a policy changes the machine’s configuration; review the command and selected file first.

Use All commands to search the complete command catalogue and fill in options that do not have a dedicated panel. Review the command preview before running it. Commands requiring interactive terminal input still need a terminal.

4.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 file

bbx 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.