BitBoxBridge lets supported web wallets communicate with your BitBox on a desktop or laptop computer. It does not run on phones or tablets, and you do not need it for normal BitBoxApp use.

If a connection that uses Bridge fails, first check whether its local status page opens on your computer. Then follow the branch for your result. Some web-wallet connections work without Bridge, so check your wallet's connection guide before installing or reinstalling it.

Before you start

Open the wallet’s official website or browser extension on your computer.

  1. Close the BitBoxApp and other wallet applications that might be using your BitBox.
  2. Connect your BitBox by USB. If you use a cable, make sure it supports data transfer. Try a direct USB port rather than a hub or dock when possible.
  3. Keep your firewall, antivirus and other computer protections enabled for the initial checks. A separate optional antivirus test is described later.

Connection troubleshooting does not require wallet secrets

Never enter recovery words, a private key, your device password or an optional passphrase into a website, and never upload a wallet backup. Enter device-unlock information only on your BitBox. Do not reset the device or restore a backup to fix a connection problem. Stop if a website asks you to do so.

 

Check whether BitBoxBridge is reachable

  1. On the computer where Bridge is installed, open a new browser tab.
  2. Enter http://127.0.0.1:8178/ in the address bar and open it. This is an address on your own computer.
  3. Look for a plain page beginning with BitBoxBridge v followed by a version number. It also lists entries such as GET /api/info. The version can differ from the example below.
Example BitBoxBridge local status page showing version 1.6.0 and API endpoints

If the page appears: Bridge is reachable, but this does not yet confirm device access or website permission. Skip the next section and continue with If Bridge is reachable but the wallet cannot connect.

If the page does not load, or you see an unexpected page, follow the next section. Note the browser's exact error rather than assuming which program caused it.

If the local status page does not load

  1. Check that you entered the complete address above, including http:// and :8178. Try http://localhost:8178/ as an alternative. Record whether one address works while the other does not.
  2. If Bridge has not been installed, use the official Bridge installation guide. Download only from the official BitBox download page or BitBoxSwiss GitHub releases. If installation fails, use the installation-error guidance below.
  3. If Bridge is already installed, save your work and restart the computer. Bridge normally starts as a background service. After restarting, leave wallet applications closed and open the local status address again.

If the page now appears, continue with the web-wallet connection checks. If it still does not appear, check for a specific security-software notification or browser error as described below. Repeatedly reinstalling Bridge will not identify the cause of a blocked connection.

If the installation was interrupted or Bridge was removed, reinstalling may be appropriate. Follow the installation guide; if you need to remove an existing installation first, ask Support for the steps for your operating system. If you are unsure whether the service is installed or blocked, contact Support with the status-page result before removing software.

If Bridge is reachable but the wallet cannot connect

  1. Return to the wallet's official website or extension and use its hardware-wallet connection option. Keep the BitBoxApp and other wallet applications closed.
  2. Disconnect and reconnect your BitBox, then retry the wallet's connection process. Unlock on the BitBox when prompted.
  3. If a pairing code appears, compare the complete code on the BitBox with the code in the wallet application. Confirm only if they match. If they differ, reject the pairing and stop.
  4. Check for a Bridge permission request using the next section. Not every connection displays one.

If the wallet still cannot find the device, check whether your operating system detects it over USB. Use the device-detection section of the guide for macOS, Windows or Linux. Keep security protections enabled for these checks.

  • The operating system does not detect the BitBox: try another data-capable cable or USB port, as applicable. If detection still fails, report this result to Support; a working Bridge status page alone cannot resolve a USB-detection problem.
  • The operating system detects the BitBox, but the wallet does not: note any wallet error and continue with the permission and blocking checks. Detection alone does not establish that the wallet can access the device.

Check a Bridge permission request

Bridge may ask whether a website can connect to your BitBox. This is separate from comparing a pairing code on the device or approving a transaction.

The request identifies the website by its host name, for example Allow [website host] to connect to your BitBox? Approve only a connection you just initiated, and only when the displayed host name matches the official website of the service you intended to use. Reject an unfamiliar or unexpected request and stop.

  • Windows, Bridge 1.6.1: the request is a Windows dialog titled BitBoxBridge, with Yes/No choices. It has a limited response time. If you missed it, retry the connection from the wallet to request permission again.
  • macOS and Linux, Bridge 1.6.0: the request opens in a browser page on your computer, with Accept and Reject buttons. Check the requesting host before selecting Accept.

Some hosts are already allowed, so the absence of a prompt does not by itself indicate a fault. If you reject a request, the wallet will not receive that approval. If an expected prompt fails to appear and the connection remains blocked, tell Support your Bridge version and operating system rather than disabling protections to force the connection.

Check for security-software or browser blocking

First check your browser's site permissions and your security software's notifications or blocking history. Look for an entry that specifically names Bridge, the wallet's website or 127.0.0.1:8178. Record the exact message. A connection failure alone does not identify the VPN, firewall or antivirus as its cause.

If a tool identifies a block, ask Support or the software provider whether a narrowly scoped permission is appropriate. Do not create a broad exclusion or allow an unfamiliar website. On a computer managed by your employer or organization, ask the system administrator to investigate instead of changing protection settings yourself.

Optional: test whether antivirus affects the local status page

If the local page still will not open after the address and restart checks, and the notifications do not explain why, a brief antivirus test can provide another clue. Use it only on your own trusted computer, with Bridge already installed from an official source. Do not run this test if the antivirus reports a threat or has quarantined the installer. If the local page already opens, this test will not diagnose a USB or web-wallet permission problem.

Before starting, make sure you know how to pause and restore the relevant protection using your antivirus provider's instructions. If you are unsure, ask Support or the provider rather than proceeding.

  1. Disconnect your BitBox. Close wallet applications, unrelated applications and other browser tabs. Keep only the local status-page tab open.
  2. Briefly pause only the antivirus protection you are investigating. Leave the firewall, VPN and other protection layers unchanged. Do not uninstall the antivirus or bypass tamper protection.
  3. Reload http://127.0.0.1:8178/ once and note whether the Bridge status page appears. During this test, do not browse other websites, download or install files, open a wallet, enter secrets or sign anything.
  4. Immediately restore the antivirus protection, whether the page loaded or not, and confirm that it is enabled. Reload the same address once more with protection enabled and record the result.
  • The page opens only while protection is paused: this points to interference from that protection, but does not prove that a detection is a false alarm. Keep protection enabled and give Support or the antivirus provider the results so they can investigate a specific remedy.
  • The result does not change: the test has not identified that protection as the cause of the local-page failure. Keep it enabled and report the unchanged result to Support. This does not rule out blocking elsewhere in the connection.

A working connection with protection disabled is a diagnostic result, not a lasting fix. Restore any protection you previously disabled before continuing.


If installation fails, including “The pipe is being closed”

This error does not by itself identify antivirus software as the cause. Close the failed installer and note the exact error and when it appeared. Confirm that you obtained the installer from the official BitBox download page and selected the package for your operating system.

Keep antivirus and other protections enabled. If they report a detection or quarantine the installer, do not override the warning or add an exclusion to complete installation. Contact Support with the installer filename, operating system, error and any security-tool notification. If no such notification appears but installation still fails, send the same details without assuming a cause.

Recognize a working connection or contact Support

The connection is complete when the wallet's hardware-wallet flow finishes and displays the account you intended to open. The Bridge status page alone is not that confirmation. You do not need to send funds or sign a transaction to test connectivity. Before using an address for a payment, follow the wallet's receiving-address verification procedure on your BitBox.

If the connection still fails, or a pairing code differs, contact BitBox Support. Include what you know; you do not need to complete every check before asking for help:

  • Your operating system and version, browser and version, and the wallet website or extension you are using.
  • Your BitBox model and firmware version, if available.
  • The Bridge version shown on the local page, or that neither local address loads.
  • The step that fails, exact error, whether the operating system detects the BitBox, and whether a permission request appeared.
  • Any specific security-tool notification and the checks you have already tried.

Never send recovery words, wallet backups, private keys, passwords or passphrases. Remove unrelated account information and other private details from any screenshot before sharing it.