Connect the BitBoxApp to your own Bitcoin full node to view your Bitcoin account balances and transaction history through infrastructure you control instead of public servers.
You can connect through Tor using an onion address or connect directly when the BitBoxApp and your node are on the same local network. The connection method and port depend on the node software you use.
Before you begin
Make sure your node setup includes:
- A fully synchronized Bitcoin full node, such as Bitcoin Core.
- A fully synchronized Electrum-compatible server, such as Electrs, Electrum Personal Server (EPS), or Bitcoin Wallet Tracker (BWT).
- The connection endpoint supplied by your node software. This normally contains a hostname or IP address and a port.
- The latest version of the BitBoxApp.
The BitBoxApp does not connect directly to Bitcoin Core. Instead, it connects to an Electrum-compatible server, which prepares your blockchain data so the BitBoxApp can quickly retrieve Bitcoin account balances and transaction history.
If the Electrum server is still indexing, wait until it reports that synchronization is complete before continuing.
Choose how to connect
Use the connection information displayed by your node software. Do not replace its port with 50001 or 50002 unless the node instructions specifically tell you to do so.
| When should you use this connection? | Connection to use |
|---|---|
| The BitBoxApp and node are on the same local network, and the node provides a local endpoint | Connect directly using the local IP address or hostname and the supplied port. |
| Your node provides an onion address | Connect through Tor using the complete onion endpoint. You can use this method at home or away from home. |
| You want to connect while away from home, and your node supports VPN access | Connect to your home network through the VPN, then use the VPN endpoint supplied by your node software. |
Recommended connection method
- Local network: The best choice when the BitBoxApp and your node are on the same local network.
- VPN: Recommended for secure remote access to your home network. Many users use VPN solutions such as Tailscale when supported by their node software.
- Tor: A good alternative when your node provides an onion endpoint or when you prefer Tor-based connectivity.
Some node packages provide more than one connection method. You can normally connect locally while at home and use Tor or a supported VPN while away from home. Do not expose the Electrum server to the public internet through port forwarding.
To add an endpoint, open Settings → Advanced settings → Connect your own full node.
Connect through Tor
Use these steps when your node provides an address ending in .onion.
Set up the Tor proxy
Tor must be installed and running on the same computer as the BitBoxApp.
- Open and connect the Tor Browser, or start your Tor background service.
- Open the BitBoxApp.
- Select Settings.
- Open Advanced settings.
- Select Enable tor proxy.
- Enable the proxy.
- Enter the proxy address that matches your Tor setup:
- Tor Browser normally uses
127.0.0.1:9150. - A Tor background service normally uses
127.0.0.1:9050.
- Tor Browser normally uses
- Select Set proxy address.
- Close the BitBoxApp completely and open it again.
For more information about the proxy setting and connection-refused errors, learn how to configure the BitBoxApp with Tor.
Add the onion endpoint
- Open the page in your node software that displays connection information for wallets or Electrum clients.
- Copy the complete onion endpoint, including its port. It will have a format similar to
your-node-onion-address.onion:port. - In the BitBoxApp, select Settings.
- Open Advanced settings.
- Select Connect your own full node.
- Paste the onion endpoint into the endpoint field.
- If your node identifies the endpoint as TLS, follow its certificate instructions. Do not change the supplied port.
- Select Check.
- Wait for the BitBoxApp to confirm that the connection was established successfully.
- Select Add.
Keep Tor running whenever the BitBoxApp connects to the onion endpoint. If you use Tor Browser as the proxy, the browser must be open and connected to Tor.
Connect on your local network
Use these steps when the BitBoxApp and your node are on the same local network and the node provides a local endpoint.
TLS connections require the BitBoxApp to trust your node's certificate before a secure connection can be established.
- Open the page in your node software that displays connection information for wallets or Electrum clients.
- Copy the complete local endpoint. It will have a format similar to
local-IP-or-hostname:port. - Open the BitBoxApp.
- Select Settings.
- Open Advanced settings.
- Make sure Enable tor proxy is disabled if you want the BitBoxApp to connect directly over the local network.
- Select Connect your own full node.
- Paste the local endpoint into the endpoint field.
- If the node provides a TLS endpoint, select Download remote certificate.
- Select Check.
- Wait for the BitBoxApp to confirm that the connection was established successfully.
- Select Add.
The local endpoint normally works only while the BitBoxApp is connected to the same home or local network as the node.
Connect remotely through a VPN
If you want to use your Bitcoin full node while away from your home network, you can connect to your local network through a VPN.
Some node packages, such as Umbrel, support VPN solutions like Tailscale. Once your computer is connected to the VPN, the BitBoxApp can usually connect to your node using its VPN IP address, similar to being on the same local network.
Your node still requires an Electrum-compatible server.
For setup instructions, follow the documentation provided by your node software or VPN solution.
Use only your own node
Removing the default BitBox servers ensures that the BitBoxApp retrieves Bitcoin account balances and transaction history only from your own Bitcoin infrastructure. If your node becomes unavailable, the BitBoxApp cannot update your Bitcoin accounts until the connection is restored.
First confirm that the BitBoxApp connects successfully and loads your Bitcoin accounts through the new endpoint.
If you want the BitBoxApp to use only your own node, remove the default BitBox servers from the full-node settings after the new connection works.
Troubleshoot the connection
The connection check times out or fails
Check the following:
- The Bitcoin full node is fully synchronized.
- The Electrum server is installed, running, and fully indexed.
- You copied the complete endpoint and port from the node software.
- The node is reachable from your current network, such as your local network, Tor, or VPN.
- You did not substitute a different port based on another node guide.
The BitBoxApp reports connection refused when using Tor
The BitBoxApp cannot reach the local Tor proxy.
- Make sure Tor Browser or the Tor background service is running.
- Confirm that the complete proxy address matches your Tor setup: normally
127.0.0.1:9150for Tor Browser or127.0.0.1:9050for a background service. - Close the BitBoxApp completely and open it again.
The BitBoxApp cannot download the certificate
Confirm that the endpoint is identified as a TLS endpoint by your node software. A non-TLS endpoint does not provide a TLS certificate.
If your node supplies separate TCP and TLS endpoints, copy the TLS endpoint exactly as displayed instead of manually changing its port.
Bitcoin accounts no longer update
If you removed the default BitBox servers, the BitBoxApp cannot update your Bitcoin accounts when your own node connection is unavailable.
Check the node, Electrum server, local network, and Tor proxy as applicable. To restore access temporarily, add the default BitBox servers again or reset the full-node connection settings to their defaults.
Frequently asked questions
Does connecting to my own node affect my bitcoin?
No. Connecting the BitBoxApp to your own Bitcoin full node only changes where the BitBoxApp retrieves Bitcoin account balances and transaction history. Your bitcoin remain protected by your BitBox and are never moved or modified.
What happens when my node is offline?
If the BitBoxApp is configured to use only your own node, Bitcoin accounts cannot update until the node connection is available again. Your bitcoin and the wallet stored on your BitBox are not affected.
Can I use Umbrel, Start9, or another node package?
Yes. The BitBoxApp works with any Bitcoin full node setup that provides an Electrum-compatible server and the required connection endpoint. Always use the connection details supplied by your node software.
Do I need Tor when the BitBoxApp and node are on the same network?
No. You can use a local endpoint when your node software provides one. You can also use the node's onion endpoint from the same network if that is the connection method supplied or preferred by your node package. A VPN connection to your home network is another option if your node software supports it.
Should I use port 50001 or 50002?
Use the exact port displayed by your node software. Port numbers commonly indicate different connection types, but they are not universal across all node packages and configurations.
Does Tor replace the need for my own full node?
No. Tor changes how the BitBoxApp reaches a server. Connecting to your own full node changes which Bitcoin infrastructure supplies your Bitcoin account balances and transaction history.