On current BTCPay Server Docker deployments, including version 2.4.5 and later, Tor is opt-in. Enable it on the server with sudo btcpay-fragments add opt-add-tor, wait for the Docker stack to reconcile, then read the BTCPay onion hostname from the generated Tor volume or the administrator’s Settings/Services screen. Open that .onion address in Tor Browser to test reachability. The separate Bitcoin P2P onion address is not the address customers or administrators should normally use, and it should not be shared with untrusted parties.
What changed in BTCPay Server 2.4.5
BTCPay Server 2.4.5 changed the Docker deployment behavior from Tor included by default to Tor enabled only when an operator requests it. The release announcement dated October 5, 2026 describes the change this way: “Tor remains supported, but is no longer included by default.” Its stated purpose is to reduce the default attack surface and resource use while preserving the option for operators who need onion access.
As an Amazon Associate I earn from qualifying purchases.
This matters most after an upgrade. A server that used Tor on an older deployment should not assume that a new 2.4.5-or-later stack will automatically recreate the Tor services. Run the opt-in command after updating. Existing Tor data is preserved through the current Tor volumes, so an existing onion identity can be retained when the stack is reconciled.
Crashes, 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 minuteWindows 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 reinstall| Deployment behavior | Tor state | Operator action | Tor data |
|---|---|---|---|
| BTCPay Server before 2.4.5 | Older documentation describes Tor as activated by default. | Follow the deployment’s existing configuration and verify which services are running. | Not stated as a migration change in the current release guidance. |
| BTCPay Server 2.4.5 and later | Tor is opt-in rather than part of the default stack. | Run sudo btcpay-fragments add opt-add-tor. |
Existing Tor data is preserved through the current Tor volumes. |
The older deployment FAQ can still say that Tor is activated by default because it describes earlier behavior. For a current Docker installation, use the dated 2.4.5 release guidance and explicitly enable the fragment.
#1 Best Overall
What you need before enabling Tor
This procedure is for the official BTCPay Server Docker deployment: the setup that generates and operates a Docker Compose stack. It is not a generic Tor configuration for an arbitrary application container.
- A running BTCPay Server Docker installation with administrative access to the host.
- Permission to run commands with
sudo. - A Tor-capable client, normally Tor Browser, for the final reachability test.
- Enough capacity for the Bitcoin and Lightning workloads you already run. BTCPay’s baseline FAQ lists 2 GB of RAM, 80 GB of storage with pruning enabled, and Docker for a Bitcoin-and-Lightning node. These are baseline requirements, not a performance guarantee for every workload.
Tor is useful when a home or office server has difficult inbound networking. BTCPay identifies several common obstacles that onion services can avoid: opening multiple firewall ports, configuring NAT or port redirection, arranging DNS for an HTTPS certificate, and maintaining a fixed IP address for Lightning connectivity.
Those conveniences do not mean that every part of BTCPay is carried over Tor. BTCPay’s architecture documentation describes Tor as providing hidden services and selected onion connectivity. It does not turn the entire installation into an anonymous network endpoint.
Enable Tor on a current Docker deployment
-
Confirm that you are on the Docker host
Run the procedure from the server where BTCPay’s generated Docker Compose stack and volumes are managed. If you administer several hosts, check the hostname or other local identifier first so that you do not enable Tor on the wrong instance.
-
Add the Tor fragment
Run this command exactly:
sudo btcpay-fragments add opt-add-torThe
opt-add-torfragment adds Tor support to the generated BTCPay stack. On a 2.4.5-or-later deployment, this is the explicit opt-in step. -
Let the generated stack reconcile
After the command completes, allow BTCPay’s generated configuration to reconcile. Containers may restart as the Compose stack is updated. Do not treat a brief interruption during reconciliation as proof that the change failed; wait for the stack to settle before testing the address.
-
Keep the existing Tor volumes
Do not remove the generated Tor volumes during an upgrade or cleanup. The 2.4.5 release guidance says existing Tor data is preserved through the current Tor volumes. Retaining those volumes is how an established onion identity can continue to be available after the opt-in change.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Read the BTCPay service hostname
Once reconciliation has finished, retrieve the BTCPay onion hostname with:
cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostnameRank #2
Sale
The Psychology of Money: Timeless lessons on wealth, greed, and happiness- Ideal for Gifting
- Ideal for a bookworm
- Compact for travelling
The command should print a hostname ending in
.onion. Copy it without adding a slash, changing characters, or substituting the hostname for another service.
Find the address in the BTCPay interface
An administrator can also view the same onion address in BTCPay Server’s Settings/Services area. Use the interface as a cross-check against the file on the Docker host. If the interface and file appear to show different values, first make sure you are looking at the same server and that the stack has completed reconciliation; do not guess which address is correct.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The file path contains two important directory names:
generated_tor_servicesdiris the Docker volume holding generated Tor service data.BTCPayServer/hostnameis the hostname for the BTCPay web service.
The Bitcoin peer-to-peer service has a different hostname. Read it with:
cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTC-P2P/hostname
Do not use the BTC-P2P value as the BTCPay web URL. It is a node-to-node endpoint, not the login and interface address.
Verify that the onion service works
-
Use Tor-capable software
Open Tor Browser, or another client that is explicitly configured to connect through Tor. A normal browser using the clearnet network cannot resolve or reach a
.onionservice. -
Enter the BTCPay hostname
Paste the value from the
BTCPayServer/hostnamefile into the browser’s address bar. Use the hostname as supplied; do not replace it with theBTC-P2Phostname. -
Wait for the onion connection
Onion connections can take longer to establish than an ordinary local or clearnet page. Wait for the page to finish loading rather than refreshing repeatedly during the initial connection.
-
Confirm the BTCPay interface
A successful test reaches the BTCPay login or interface over the onion address. Sign in only if you intended to access the server and are using the expected hostname.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
This test answers one question: whether the published BTCPay onion service is reachable through Tor from that client. It does not measure latency, uptime, throughput, or the privacy of every other connection made by the deployment.
Tor access versus clearnet HTTPS
Tor and a conventional HTTPS address solve different operational problems. Choose the access method based on who must reach the server and what networking you can operate.
| Consideration | BTCPay onion access | Clearnet HTTPS access |
|---|---|---|
| Inbound network requirements | Designed to avoid the need for multiple publicly reachable firewall ports and NAT port forwarding. | Usually requires the relevant inbound ports, firewall rules, and NAT or reverse-proxy configuration. |
| DNS and certificate setup | Uses a Tor .onion hostname; ordinary public DNS and a conventional certificate are not the basis of access. |
Normally depends on a DNS name and HTTPS certificate provisioning. |
| Client software | Requires Tor Browser or another Tor-capable client. | Works in ordinary browsers and standard HTTPS clients. |
| Operational observability | Connections arrive through the onion service and can be harder to observe with tools designed for public web traffic. | Fits conventional firewall, reverse-proxy, DNS, and web-monitoring workflows. |
| Privacy and security scope | Provides selected onion connectivity and hidden services; it does not make every BTCPay connection anonymous. | Provides ordinary encrypted web access but does not provide Tor’s onion routing properties. |
Some operators expose both methods: an onion address for administration or users who need it, and clearnet HTTPS for clients that cannot run Tor. Running both does not change the scope of Tor inside the stack; it simply provides two access paths to the services that BTCPay exposes.
What enabling Tor does—and does not—protect
It can simplify difficult inbound connectivity
An onion service can make a BTCPay installation reachable without arranging a fixed public IP, opening several firewall ports, forwarding ports through a home router, or configuring public DNS for a certificate. That is particularly useful for self-hosting from a home or office connection where inbound rules are controlled by an ISP router or are not available at all.
It does not anonymize the whole installation
BTCPay’s architecture documentation says Tor provides hidden services and selected onion connectivity. The deployment FAQ also warns that activating Tor does not guarantee privacy or prevent clear-net connections. Services that are not covered by the onion configuration may still communicate over their normal network paths. A targeted observer may also correlate activity using information outside the Tor connection.
It does not make the Bitcoin P2P address safe to publish
BTCPay warns that the Bitcoin P2P onion service is whitelisted by the node. Sharing that endpoint with untrusted parties can expose the node to malicious peers and denial-of-service traffic. Treat the BTC-P2P hostname as a separate, sensitive operational endpoint. Use the BTCPayServer hostname for the web interface and share the P2P value only when you have a specific, trusted reason.
Troubleshoot a missing or unreachable onion address
The opt-in command was never run
On 2.4.5 and later, Tor is not part of the default Docker stack. Run sudo btcpay-fragments add opt-add-tor, then wait for the generated stack to reconcile before checking the hostname file.
The hostname file is missing
Check that you are on the correct Docker host and that the volume path is spelled exactly as shown. A missing file immediately after the command can mean that reconciliation is still in progress. Wait for the stack to settle and check again. If the volume was deleted manually, the previous Tor data may no longer be available; do not remove volumes as a first troubleshooting step.
Recommended Free Tools
Rank #4
The address is opened in a normal browser
A standard browser on the clearnet cannot reach a .onion hostname. Repeat the test in Tor Browser or another Tor-capable client. If Tor Browser itself cannot connect to any onion service, resolve the client’s Tor connection before diagnosing BTCPay.
The wrong hostname was copied
Compare the path segment in the command output. BTCPayServer/hostname is the web interface; BTC-P2P/hostname is the Bitcoin peer-to-peer service. A P2P hostname will not present the BTCPay login page.
The address changed after an upgrade
Check whether the generated Tor volumes are still present and whether the stack was rebuilt on the same host. The 2.4.5 guidance preserves existing Tor data through the current volumes, but deleting or replacing those volumes changes the conditions under which that preservation works. Re-read the hostname file and update any internal documentation only after confirming the new value in Tor Browser.
The page loads but a connection still appears to use the clearnet
Successful onion access does not prove that every BTCPay component uses Tor. Review the specific service involved and BTCPay’s documented architecture. Do not describe the installation as fully anonymous merely because the web interface opens through an onion address.
Operational checklist
- Confirm the server is running the official BTCPay Docker deployment.
- For version 2.4.5 or later, run
sudo btcpay-fragments add opt-add-tor. - Allow the generated Compose stack to reconcile and restart as needed.
- Keep the existing generated Tor volumes so their data can be preserved.
- Read
/var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostname. - Open that hostname in Tor Browser, not an ordinary browser.
- Confirm that the page is the BTCPay login or interface.
- Keep the separate
BTC-P2Phostname private and do not publish it to untrusted parties. - Document that Tor provides selected onion connectivity, not whole-installation anonymity.
When Tor is the right choice
Enable Tor when the main problem is inbound reachability: a home server behind NAT, an office network with restricted firewall control, no stable public IP, or a desire to avoid public DNS and conventional certificate provisioning for the BTCPay endpoint. The trade-off is that every user must have Tor-capable software, and the onion path does not replace ordinary monitoring or security practices.
Keep clearnet HTTPS as the primary path when customers, payment integrations, or administrators cannot use Tor and you can responsibly operate public networking, DNS, and certificates. In either design, verify the exact service hostname, protect the Bitcoin P2P endpoint, and treat Tor as a targeted connectivity feature rather than a blanket privacy guarantee.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Bottom line
For BTCPay Server Docker 2.4.5 and later, Tor must be enabled explicitly with sudo btcpay-fragments add opt-add-tor. Retrieve the web service address from the generated BTCPayServer/hostname file, open it in Tor Browser, and keep the separate BTC-P2P address private. The result is useful onion access for selected BTCPay services—not an anonymous version of the entire deployment.
Frequently Asked Questions
Is Tor enabled automatically on BTCPay Server Docker?
Not on current 2.4.5-and-later Docker deployments. Tor changed from included by default to opt-in. Run sudo btcpay-fragments add opt-add-tor on the Docker host, then allow the generated Compose stack to reconcile. Older deployment documentation may describe automatic activation because it reflects pre-2.4.5 behavior.
Free tools Windows power users keep installed
One-click scans. No signup required.
Where can I find my BTCPay .onion address?
Read /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostname on the Docker host. An administrator can also view the address in BTCPay Server’s Settings/Services area. The value in the BTCPayServer directory is the web interface hostname; the separate BTC-P2P directory contains the Bitcoin peer-to-peer hostname.
Best Value
- It can be a gift option
- Comes with secure packaging
- Helpful in various ways
How do I test whether the onion service works?
Copy the hostname from the BTCPayServer/hostname file into Tor Browser or another Tor-capable client. A successful test displays the BTCPay login or interface. A normal browser cannot resolve a .onion address. This confirms reachability from that client, not uptime, throughput, latency, or Tor use by every other component.
Will enabling Tor preserve my existing onion address after an upgrade?
The 2.4.5 release guidance says existing Tor data is preserved through the current Tor volumes. Keep those generated volumes during upgrades and cleanup. Deleting or replacing them removes the conditions needed for that preservation, so recheck the hostname file after any rebuild.
Does Tor make my whole BTCPay installation anonymous?
No. BTCPay documents Tor as providing hidden services and selected onion connectivity, and its deployment FAQ warns that activation does not guarantee privacy or prevent clear-net connections. Components outside the onion configuration can continue using normal network paths, and onion access does not protect against every targeted correlation or observation risk.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsCan I share the Bitcoin P2P onion hostname?
Treat it as sensitive. BTCPay warns that the Bitcoin P2P onion service is whitelisted by the node and should not be shared with untrusted parties because malicious peers could DDoS the node. Use the BTCPayServer hostname for the web interface and disclose the BTC-P2P value only for a specific, trusted operational reason.
What hardware does a Tor-enabled BTCPay node need?
BTCPay’s baseline FAQ lists Docker, 2 GB of RAM, and 80 GB of storage with pruning enabled for running Bitcoin and Lightning nodes. Those figures are baseline requirements, not a performance guarantee for every workload. Tor does not remove the capacity needs of the Bitcoin, Lightning, and BTCPay services already running on the host.
Should I use Tor or clearnet HTTPS for customers?
Use Tor when avoiding public inbound ports, NAT forwarding, fixed-IP requirements, or conventional DNS and certificate setup is the priority. Use clearnet HTTPS when customers, payment integrations, or administrators cannot run Tor and you can operate public networking responsibly. Some operators provide both paths, but dual access does not expand Tor’s privacy scope.
Why is my onion hostname missing immediately after I enable the fragment?
The generated stack may still be reconciling or restarting. Wait for the update to settle, then check the exact volume path and confirm that you are on the correct Docker host. Do not delete volumes as a first troubleshooting step; removing generated Tor data can eliminate the existing onion identity.
The Bottom Line
On BTCPay Server Docker 2.4.5+, run sudo btcpay-fragments add opt-add-tor, read the web hostname from BTCPayServer/hostname, and test it in Tor Browser. Keep the separate BTC-P2P onion endpoint private, and remember that selected onion access is not whole-installation anonymity.
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.
