Connect the BitBoxApp to your own Bitcoin full node to retrieve balances and transaction history, and broadcast signed Bitcoin transactions, through infrastructure you control. The BitBoxApp connects through an Electrum-compatible server that provides access to your node’s blockchain data, rather than directly to Bitcoin Core.
You can connect from a computer or phone, including from outside your home network through a VPN. Adding your server keeps the existing servers available as alternatives. To use only your own Bitcoin infrastructure, you must also remove those alternatives and restart the app, as described below.
Before you begin
You need the latest BitBoxApp and a fully synchronized Bitcoin node with an Electrum-compatible server that has finished synchronizing and indexing. Node packages such as Umbrel, Start9, or RaspiBlitz may provide this server; check your package’s documentation for its setup and connection details.
For a self-managed installation, electrs and ElectrumX are examples of Electrum servers. Compatibility depends on the backend release and Bitcoin Core version you use. Follow the documentation for the release you install, including its storage and indexing requirements.
Pruning support depends on the Electrum server, rather than on a separate BitBoxApp pruning setting. Both electrs and ElectrumX require an unpruned Bitcoin Core node. If you use another backend with a pruned node, check that it can supply the historical data and Electrum functions the BitBoxApp needs.
The same applies to disablewallet=1: disabling Bitcoin Core’s wallet functionality is suitable only if your backend does not depend on it. This setting does not make a backend compatible with pruning.
Before continuing, obtain the server’s Electrum endpoint: a hostname or IP address followed by a port, such as hostname:port. Use the endpoint and connection type supplied by your node software, rather than its Bitcoin Core RPC address. Do not substitute 50001 or 50002 unless your node’s instructions specify that port.
Choose how to reach your node
Choose a connection your node provides, then prepare it before adding the endpoint in the BitBoxApp.
| Your setup | Connection to use |
|---|---|
| Your computer or phone and node are on the same local network. | Use the local Electrum endpoint. It normally works only while you are on that network. |
| You want to connect from outside your home network. | Connect your computer or phone to a VPN that provides access to your node, then use the Electrum endpoint reachable through that VPN. The Tailscale example below explains this approach. |
You use the desktop BitBoxApp and your node provides an address ending in .onion. |
Use its complete onion endpoint through Tor. This can work at home or remotely. |
For an onion endpoint on desktop, first configure the BitBoxApp’s Tor proxy. The onion endpoint must reach the Electrum server, not just your node’s administration page. Keep Tor running while you use that endpoint. The BitBoxApp’s Tor proxy option is unavailable on iOS; use a local or VPN connection there.
For a direct local or VPN connection, disable Enable tor proxy in Settings → Advanced settings if it is enabled, then close and reopen the BitBoxApp so it connects directly.
Do not expose your Electrum server to the public internet through router port forwarding. Use your local network, a VPN, or the node’s onion endpoint for access.
Use your node away from home with a VPN
A VPN can make your node reachable while your phone uses mobile data or your computer connects to another network. Tailscale is one option: it creates a private, encrypted network between your devices. Your node still needs a synchronized Electrum server.
- Install Tailscale on the machine running your node and add it to your Tailscale network. If you use Umbrel, you can install the Tailscale app from the Umbrel App Store. Follow your node software’s instructions to complete its setup.
- Install Tailscale on the phone or computer running the BitBoxApp and connect it to the same Tailscale network, using the same account for a simple personal setup. Follow the Tailscale setup guide, including any device authorization or VPN permissions it requires.
- Find your node host’s Tailscale IP address in Tailscale. Use that address with the Electrum port supplied by your node software. The Electrum service must be reachable at this address and port; being able to open the node’s administration page does not confirm Electrum access.
Keep Tailscale connected, then follow Add your Electrum server below using this endpoint. Complete the exclusive-use and remote verification steps afterward. Tailscale is a third-party networking service, and access depends on your devices remaining authorized and connected.
Add your Electrum server
Once the node and Electrum server are ready and reachable through your chosen connection, add the endpoint. You do not need to enter recovery words, private keys, or a wallet backup to configure this connection.
- Open Settings in the BitBoxApp, using the bottom navigation on a phone. Select Advanced settings → Connect your own full node, then Bitcoin Electrum servers if necessary.
- Under Add a server, enter the complete Electrum endpoint in the
host:portfield.
If the endpoint uses TLS, paste the server certificate into the certificate field, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. Obtain it through trusted access to your own node. Alternatively, select Download remote certificate and compare the downloaded certificate with the one supplied by your node through that trusted access. Stop if they differ or you cannot establish that it belongs to your node.
For a non-TLS endpoint, leave the certificate field empty; use only the connection type your node provides.
- Select Check. Wait for the message Successfully established a connection to followed by your endpoint, then dismiss the message. If the check fails, resolve the error before continuing.
- Select Add. Your endpoint appears in the Servers list. Close the BitBoxApp completely and reopen it to apply the changed server configuration.
A successful check confirms that the app can establish an Electrum connection to the endpoint. It does not test every wallet operation or confirm that the app is using only your node.
Use only your own node and verify the result
If other Bitcoin servers remain configured, the BitBoxApp can use them as alternatives. To keep Bitcoin account queries and transaction broadcasts on your own infrastructure, remove every server you do not control.
- Return to Settings → Advanced settings → Connect your own full node → Bitcoin Electrum servers. Find your endpoint in the Servers list and select its Check button to confirm it is reachable.
- For each default or other third-party Bitcoin server, select Remove beside that endpoint and confirm its removal. Leave your own working endpoint in the list.
- Close the BitBoxApp completely and reopen it. Open your Bitcoin account and wait for synchronization to finish. Confirm that the account can update its balance and transaction history without a connection error. With only your own endpoint configured, those updates depend on your node.
- If you configured VPN access, test it from outside your home network. On a phone, turn off Wi-Fi temporarily and use mobile data; on a computer, use another network. With the VPN connected, close and reopen the BitBoxApp and confirm that your Bitcoin account synchronizes without a connection error. Restore Wi-Fi if you turned it off.
With only your own endpoint configured, Bitcoin transactions you send from the BitBoxApp are broadcast through that Electrum server and your node, including when you connect over the VPN. Checking account synchronization verifies remote data access; it does not test transaction broadcasting.
Keep the node, Electrum server, and any required VPN or Tor connection running. If they become unavailable, the app cannot update your Bitcoin accounts or broadcast Bitcoin transactions through that endpoint. Changing the server configuration does not itself move bitcoin or change your BitBox wallet’s private keys.
This setting covers the Bitcoin backend. It does not route every BitBoxApp service through your node. See what data the BitBoxApp shares for the boundaries of other accounts and services.
Troubleshoot the connection
The connection check fails or times out
- Confirm that Bitcoin Core is synchronized and the Electrum server has finished its own synchronization and indexing.
- Check that the backend release supports your Bitcoin Core version and configuration, including pruning, required indexes, and whether Core’s wallet functionality must be enabled.
- Copy the Electrum endpoint and port again from your node software. A Bitcoin Core RPC endpoint is not an Electrum endpoint.
- Check that the endpoint is reachable from the device running the BitBoxApp: join the local network, connect the VPN, or start the desktop Tor proxy as appropriate. The BitBoxApp’s proxy setting must match the connection you chose.
- For Tailscale, confirm that both devices are connected to the same Tailscale network and authorized to communicate. Check that the node’s Electrum port is reachable through its Tailscale address. Follow Tailscale’s device-connectivity troubleshooting if network access fails.
If you see connection refused while using Tor, check that the local Tor proxy is running and that its address matches the BitBoxApp setting. Follow the Tor setup and troubleshooting guide.
The certificate cannot be downloaded or verified
A non-TLS endpoint does not provide a TLS certificate. If your node supplies separate TCP and TLS endpoints, use the exact endpoint intended for your chosen connection type. For a TLS endpoint, check the current certificate through trusted access to your node; do not accept an unexplained certificate change or switch to an unencrypted connection just to bypass an error.
The connection check succeeds, but the account does not update
Restart the BitBoxApp after changing the server list, and check the Electrum server’s synchronization state and logs. A backend must support the app’s wallet operations, including address-history queries and subscriptions, transaction retrieval, block headers and transaction proofs, fee information, and transaction broadcasting. A working TLS connection or watch-only feature alone does not establish that compatibility.
If the problem persists, contact BitBox Support with your BitBoxApp, Bitcoin Core, and backend versions, whether pruning and Core’s wallet functionality are enabled, your connection method, and the exact error. Remove credentials, private endpoint details, and unrelated personal information from any screenshots or log excerpts. Never share recovery words, private keys, passwords, passphrases, or wallet backups.
Your node is unavailable
Restore the node, backend, and required network connection first. If you choose to restore the default Bitcoin servers temporarily, open Bitcoin Electrum servers, select Reset to default, and confirm. This replaces the configured Bitcoin server list with the defaults, so keep your own endpoint and certificate details if you want to add them again later. Restart the app afterward.
Using the default servers restores dependence on public infrastructure for Bitcoin queries and broadcasts. To return to exclusive use of your own node, add and check your endpoint again, remove the defaults, and restart the app.