Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →On a standard Docker installation, BTCPay Server 2.4.5 (released October 5, 2026) no longer enables Tor automatically. After updating, enable the supported Tor fragment with sudo btcpay-fragments add opt-add-tor, then retrieve separate onion hostnames for the BTCPay web interface and the Bitcoin Core peer-to-peer service. Bitcoin Core creates its own onion service through Tor’s control API when its prerequisites are met; that service is not the same as BTCPay’s web onion service.
This guide covers the current Docker workflow, hostname discovery, Bitcoin Core diagnostics, manual Tor configuration, deployment choices, and the privacy and security limits that remain after Tor is enabled.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What changed in BTCPay Server 2.4.5
The current recommendation for the official Docker deployment is to treat Tor as an opt-in component. BTCPay Server 2.4.5, released October 5, 2026, changed the default from included Tor to no Tor unless the operator adds the fragment. Existing operators who update a Tor-enabled installation should explicitly add the fragment after updating:
sudo btcpay-fragments add opt-add-torThe 2.4.5 release announcement says Tor data is preserved in the existing Tor volumes when the fragment is added. Make a current backup and verify that this command matches the release deployed on your server before changing a production installation. See the BTCPay Server 2.4.5 release announcement.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
An older BTCPay deployment FAQ still says Docker activates Tor by default. That wording predates 2.4.5 and is not consistent with the newer release announcement. For a current Docker installation, follow the dated 2.4.5 instructions and then consult the documentation matching your installed version.
What an onion-enabled BTCPay deployment provides
There are two different onion services to distinguish:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Service | Purpose | How it is created | Where its hostname is found |
|---|---|---|---|
| BTCPay web service | Opens the payment server’s administration and checkout interface over an onion URL. | Managed by BTCPay’s Docker Tor fragment. | BTCPayServer/hostname in the generated Tor services volume. |
| Bitcoin Core P2P service | Lets Bitcoin peers connect to the node through an onion address. | Bitcoin Core registers an onion service through Tor’s control API when listening and authentication requirements are satisfied. | BTC-P2P/hostname in the generated Tor services volume, or through Bitcoin Core’s network information. |
Enabling the BTCPay fragment does not turn these into one service or one hostname. A merchant may need only the web onion address, while a node operator may also use the Bitcoin Core P2P address. Treat each hostname and its access policy separately.
Prerequisites and resource requirements
BTCPay’s official Docker deployment is the recommended installation method for self-hosted production. It creates and operates a Docker Compose stack and supplies version-specific installation, configuration, backup, update, and troubleshooting guidance in the BTCPay operator guide. The deployment commonly includes BTCPay Server, PostgreSQL, NBXplorer, Bitcoin Core, Nginx with automatic HTTPS certificates, and Tor; Lightning and other components are optional. The exact stack can vary with the selected options and release.
For a server running Bitcoin and Lightning nodes, BTCPay documentation lists these minimums:
- Memory: 2 GB RAM.
- Storage: 80 GB when pruning is enabled.
Those figures are stated minimums, not a sizing guarantee for every workload. Chain growth, indexes, Lightning channels, backups, databases, and concurrent users can require more capacity. BTCPay can run on hardware you operate at home or in an office, or on hosted infrastructure. The available deployment guides are listed in the official Docker repository README: BTCPay Server Docker repository.
Enable Tor on the standard Docker deployment
1. Confirm the deployment and version
These instructions apply to the official BTCPay Docker deployment. Check the installed BTCPay version and read the release notes for that version before applying a fragment. BTCPay’s configuration reference warns that option names and defaults can change between releases.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
2. Back up before changing services
Use the backup procedure in the operator guide for your deployment. The Tor fragment should preserve existing Tor data in the current Tor volumes according to the 2.4.5 release note, but a backup gives you a recovery path if a compose regeneration, permissions problem, or unrelated update fails.
3. Add the current Tor fragment
After updating to 2.4.5 or a later release whose instructions use the same fragment, run:
sudo btcpay-fragments add opt-add-torAllow the deployment scripts to regenerate and restart the affected services. Do not substitute an old, hand-written Compose edit for the supported fragment workflow unless the documentation for your exact release tells you to do so.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches4. Verify the generated services
Confirm that the Tor container is present and healthy using the Docker and BTCPay status procedures for your release. Then read the generated hostname files described in the next section. If the files are absent, first check that the fragment was added to the deployment you actually run, that the Tor service started, and that the generated volume is mounted.
Find the BTCPay web onion address
On an unmodified official Docker deployment, BTCPay’s deployment FAQ gives this command:
cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostnameThe output is the onion hostname for the BTCPay web service. A v3 onion hostname is 56 characters before the .onion suffix; the Tor Project describes this as a protocol-format property, not a shortened alias. Open the address with an onion-capable Tor client or browser.
The path is deployment-specific. If you changed the data directory, volume name, or compose layout, locate the corresponding generated Tor services volume instead of assuming that the path above exists. The file named hostname contains the public address; the neighboring key material must not be copied or published.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Find the Bitcoin Core P2P onion address
For the Bitcoin Core peer service, the FAQ gives:
cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTC-P2P/hostnameBitcoin Core also exposes its local onion address through getnetworkinfo, the -netinfo diagnostic, and the debug log. These methods are useful when the generated volume is customized or when you need to confirm that Core itself registered the service.
Do not distribute the P2P onion hostname indiscriminately. BTCPay’s deployment FAQ warns that Bitcoin-node connections are whitelisted and that malicious peers who obtain the address could use it to send traffic that contributes to a denial-of-service attack. Share it only with peers or operators who need it, and apply the node’s normal connection and resource controls.
How Bitcoin Core creates its onion service
Bitcoin Core does not require you to write a separate HiddenServicePort entry for its automatic onion service. When Core is listening and has a Tor connection, it uses Tor’s control socket API to request an onion service. This behavior is enabled by default; setting -listenonion=0 disables it.
Authentication requirements
Core can authenticate to Tor with the Tor cookie file or with the -torpassword configuration option. With cookie authentication, the operating-system user running Bitcoin Core must be able to read Tor’s configured authentication cookie. A common failure is a permissions or group-membership mismatch between the Tor process and the Bitcoin Core process.
If the debug log reports that the authentication cookie cannot be opened, check:
- Which user and group run Bitcoin Core.
- The owner, group, and mode of Tor’s authentication cookie.
- Whether the Core process has execute permission on every parent directory.
- Whether a container boundary prevents Core from seeing the cookie path or Tor control socket.
Adjust permissions using the account and service layout documented for your installation; do not make the cookie world-readable. Enable -debug=tor for more detailed Tor connection and registration messages.
v3-only compatibility
Bitcoin Core 22.0 and later support v3 onion services only. Tor removed v2 onion-service support beginning with Tor 0.4.6. A configuration or peer list that expects a v2 address will not work with current Core and Tor. The authoritative Bitcoin Core details, including diagnostics, are in Bitcoin Core’s Tor documentation.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
BTCPay Tor settings that may matter
BTCPay exposes several Tor-related settings. Their names and defaults are version-sensitive, so use the configuration reference matching the installed release rather than copying an older example blindly.
| Setting | Equivalent option | Function |
|---|---|---|
BTCPAY_TORRCFILE |
--torrcfile |
Points to a torrc file containing hidden-service directories. |
BTCPAY_TORSERVICES |
--torservices |
Associates service keys, onion hostnames, and ports displayed in Server Settings. The exact format is documented for the deployed version. |
BTCPAY_SOCKSENDPOINT |
--socksendpoint |
Specifies the SOCKS endpoint BTCPay uses when connecting to onion URLs. |
These variables do not replace the 2.4.5 fragment command for the standard Docker deployment. They are configuration interfaces for cases covered by the release documentation, custom service mappings, or an operator-managed Tor arrangement.
Manual Tor configuration for operators who manage the service themselves
A manually managed onion service is a different operating model. Instead of letting BTCPay’s deployment fragment create the service, you manage Tor’s configuration, directories, permissions, restarts, and upgrades.
Use a hidden-service directory and port mapping
The Tor Project’s generic pattern is:
HiddenServiceDir /path/to/service-directory
HiddenServicePort 80 127.0.0.1:80HiddenServiceDir must be writable by the Tor process. Each HiddenServicePort maps the virtual port exposed on the onion service to a local address and port. The example forwards onion port 80 to a web service listening on 127.0.0.1:80; adapt the destination to the service you intentionally expose.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRestart and inspect
- Validate the torrc syntax using the Tor package’s configuration-check procedure.
- Restart Tor through the service manager used by your operating system.
- If Tor fails to start, read its service and application logs before changing permissions or paths.
- After a successful start, read the generated
hostnamefile in the hidden-service directory. - Keep the private-key files in that directory protected from other users and from backups or logs that are not encrypted.
The Tor Project’s setup guide explains that the hostname file stores the onion address and the other service files contain key material. Anyone who obtains those keys can impersonate the onion service. Its guide also notes that a Unix socket can reduce the chance of exposing a service to the local network. That is general Tor guidance, not a tested recipe for the BTCPay Docker stack; for Docker, prefer BTCPay’s version-matched fragment and configuration documentation. See Tor Project: Set up Your Onion Service.
Web onion service versus Bitcoin P2P onion service
| Decision | BTCPay web onion | Bitcoin Core P2P onion |
|---|---|---|
| Primary users | Merchant staff, customers, and applications reaching the payment interface. | Bitcoin peers and node operators. |
| Exposure concern | Account security, browser sessions, payment administration, and application-level access. | Peer traffic, bandwidth, connection limits, and denial-of-service exposure. |
| Discovery | BTCPayServer/hostname or Server Settings. |
BTC-P2P/hostname, getnetworkinfo, -netinfo, or the debug log. |
| Configuration owner | BTCPay’s Docker Tor fragment and its service mappings. | Bitcoin Core’s Tor control API, authentication, and listening settings. |
Do not troubleshoot a missing web hostname by changing Bitcoin Core’s Tor settings, or troubleshoot a missing P2P hostname by editing BTCPay’s web-service mapping. They have different control paths and logs.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Why Tor is useful on a home or office server
BTCPay documents Tor primarily as a deployment convenience. An onion address can let a merchant reach a server behind a home or office connection without exposing the same services through ordinary inbound Internet routing. Depending on the rest of the design, this can reduce the need to:
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
- Open several firewall ports.
- Configure router NAT redirection.
- Buy and maintain DNS names for an HTTPS certificate.
- Maintain a fixed public IP address for Lightning connectivity.
This is a networking simplification, not a blanket security or anonymity guarantee. A hosted server may offer different operational control, while a home server keeps hardware and network administration in your hands. BTCPay documents both approaches but does not establish provider reliability, pricing, or privacy comparisons; choose based on your own uptime, physical-security, bandwidth, and maintenance requirements.
Privacy and security limits
Tor does not make the operator anonymous
BTCPay’s deployment FAQ explicitly cautions that activating Tor is not sufficient for “perfect privacy and security.” An onion address can hide the server’s public IP from an onion client, but it does not erase payment records, account identities, node metadata, logs, browser fingerprints, or operational mistakes.
Not every connection is guaranteed to use Tor
BTCPay says it cannot guarantee that every connection made by the software, a plugin, Bitcoin, or Lightning uses Tor. Services may still have clearnet paths, and enabling Tor does not prevent clear-net access to the BTCPay instance or its nodes. Review each integration, outbound endpoint, DNS lookup, webhook, update channel, and plugin separately if your threat model requires strict routing.
Protect onion keys
The v3 hostname is public, but the service keys are private credentials. Store them with restrictive permissions, include them in encrypted backups only, and do not paste the hidden-service directory into support tickets or public repositories. If an attacker obtains the keys, they can impersonate the onion service until you replace the service identity and distribute a new hostname.
Troubleshooting checklist
The onion hostname file does not exist
- Confirm that the server is the official Docker deployment and that the Tor fragment was added to that deployment.
- Check the installed BTCPay version and follow its release-specific instructions.
- Verify that the Tor container started and that the generated volume is mounted.
- Search the deployment’s configured Docker volume location if the default
/var/lib/docker/volumes/generated_tor_servicesdir/path was customized. - Inspect Tor and deployment logs for directory, permission, or control-socket errors.
The BTCPay web onion works, but the Bitcoin P2P onion is missing
- Confirm that Bitcoin Core is listening;
-listenonion=0explicitly disables automatic onion registration. - Check that Core can reach Tor’s control socket.
- Resolve cookie-file ownership and read permissions without making the cookie public.
- Enable
-debug=torand inspect the Core debug log. - Use
getnetworkinfoor-netinfoto see whether Core reports an onion address.
The service worked before an update
On 2.4.5 and later, Tor is opt-in in the standard Docker deployment. Re-add the supported fragment with sudo btcpay-fragments add opt-add-tor after confirming the command for your release. The 2.4.5 announcement says existing Tor data remains in the current volumes, so a missing address after an update usually points to the fragment, volume, service-start, or permissions path rather than an intentional address reset.
Clients cannot connect even though a hostname exists
- Use a Tor-capable client and confirm the complete 56-character v3 hostname plus
.onion. - Check that the mapped destination service is listening on the expected container or local port.
- Review Tor logs for a failed port mapping.
- For a web service, verify BTCPay’s application and reverse-proxy status separately from Tor.
- For Bitcoin P2P, check Core’s listening, connection limits, and peer policy.
Operational checklist for production
- Record the BTCPay and Bitcoin Core versions before changing configuration.
- Back up BTCPay data and protect Tor key material in encrypted storage.
- Use the official Docker fragment for the deployed BTCPay release.
- Retrieve and securely document the web and P2P hostnames separately.
- Test access from an independent Tor client rather than only from the server itself.
- Confirm that ordinary clearnet access, DNS, webhooks, Lightning peers, and plugins match your threat model.
- Keep the P2P onion address private unless a trusted peer needs it.
- After every BTCPay update, check whether Tor remains enabled and whether configuration defaults changed.
For current option names, defaults, and deployment behavior, use the version-matched configuration reference and the operator guide. The generic Tor pattern is useful when you deliberately manage Tor yourself, but it should not replace the supported BTCPay Docker workflow.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
