Install BitBoxBridge when the instructions for your chosen web wallet require it. It is a background application for supported browser connections on Windows, macOS and Linux; you do not need it for normal use of the BitBoxApp.
After installation, BitBoxBridge starts automatically and runs in the background, including after you restart your computer. You normally do not need to open it yourself. The steps below help you install it and check that it responds locally before connecting your wallet.
1. Download BitBoxBridge
- On the computer where you will use the web wallet, open the official BitBox download page. Scroll to Download the BitBox Bridge, below the BitBoxApp downloads.
- Select the download for your operating system. For Linux, open the Linux selection and choose the
.debpackage for Ubuntu or Debian, or the.rpmpackage for Fedora or openSUSE. These instructions cover the packaged Linux installation, not manual installation from an archive.

Use the version offered for your platform. Windows, macOS and Linux do not always use the same release number. Advanced users can also find releases in the official BitBoxBridge repository.
Use the official download
Download BitBoxBridge only from the official BitBox website or BitBoxSwiss GitHub repository. If your operating system reports a security warning you do not understand, stop and contact Support before bypassing it or disabling protection.
Optional: check the download before installing
A SHA-256 checksum lets you compare the downloaded file with the one listed by BitBox. On the download page, select Show checksums in the BitBox Bridge section, not the separate BitBoxApp section.
- Find the checksum for the exact platform and file you downloaded.
- Calculate the downloaded file's SHA-256 checksum. On Windows, open PowerShell; on macOS or Linux, open Terminal. Use the command for your system below, replacing the example path inside quotation marks with the full path to your downloaded file. Check the original download before unpacking or installing it.
Windows:
Get-FileHash -Algorithm SHA256 -LiteralPath "C:\path\to\downloaded-file.exe"macOS:
shasum -a 256 "/path/to/downloaded-file.pkg"Linux:
sha256sum "/path/to/downloaded-file.deb"Use the actual .rpm filename instead if you downloaded an RPM package.
- Compare the complete calculated hash with the checksum on the official page. Letter case does not matter. If they differ, do not run the file. Download it again from the official source; if the mismatch persists, contact Support.
2. Install the downloaded file
You may need administrator permission. Choose the instructions for your computer and keep its security protections enabled.
Windows
- Open your Downloads folder, or the location where you saved the file, and double-click the BitBoxBridge
.exeinstaller. - Follow the installation prompts. If Windows requests administrator permission, approve it only for the installer you intentionally downloaded from the official source. Wait for installation to finish.
macOS
- In Finder, open the folder containing the downloaded BitBoxBridge
.pkgfile and double-click it. - Follow the installer through to completion, entering your Mac administrator password in the macOS prompt if requested. This is your computer's password, not your BitBox device password.
Ubuntu, Debian, Fedora and openSUSE
- Open the folder containing the downloaded
.debor.rpmfile and open it with your distribution's package installer. - Choose the install action, authorize it if requested, and wait for the package manager to report completion. If your system does not offer a suitable package installer or reports an error, stop and contact Support with your distribution and the error text.
The installer starts BitBoxBridge as a background service. A separate application window is not expected. Next, check that the service is reachable.
3. Check that BitBoxBridge is running
- Open a browser on the same computer and enter http://127.0.0.1:8178/ in the address bar. This address points to your own computer. You can also use http://localhost:8178/.
- Look for a plain status page beginning with BitBoxBridge v followed by a version number. It lists entries such as
GET /api/infoandGET /api/v1/devices. The example below shows version 1.6.0; your version may differ.

This response confirms that BitBoxBridge is running and reachable from your browser. You do not need to connect the BitBox for this check. It does not yet confirm that a web wallet can detect or use your device.
If the page does not load, restart your computer once and open the address again. If it still fails, contact Support with your operating system, the downloaded filename and any installation or browser error. Do not reset your BitBox or restore a backup to fix a Bridge installation problem.
Connect to your web wallet
Once the status page responds, return to the connection guide for the web wallet you intend to use. Close the BitBoxApp and other wallet applications that could be using the device, then follow that guide's hardware-wallet connection procedure. Connect and unlock the BitBox when prompted.
Keep wallet secrets out of websites
Never enter recovery words, a private key, your BitBox device password or an optional passphrase into a web wallet, and never upload a wallet backup. Enter device credentials only on the BitBox. If a website requests wallet secrets, stop and close it.
If the Bridge status page works but the wallet cannot connect, preserve the working installation and investigate the device, browser and wallet connection before reinstalling. For ordinary connection errors, see BitBoxBridge connection troubleshooting. If a security warning appears or you are unsure how to proceed, contact BitBox Support.
If installation was interrupted or Support recommends a clean reinstall, follow Uninstall BitBoxBridge, then return to this guide to install the official package and repeat the local status check. Reinstallation does not require resetting the BitBox or handling its backup.