BTCPay Docker users must opt into Tor at their next update to keep onion access
BTCPay Server version 2.4.5 requires Docker administrators to explicitly opt into Tor to maintain onion access and introduces default blocking for private-network destinations to prevent server-side request forgery.
Administrators running Bitcoin payment software BTCPay Server via its standard Docker deployment need to explicitly choose Tor during their upcoming setup or update if they wish to keep onion access. This modification excludes Tor from the default bundled components, turning what used to be an automatic feature into an explicit administrator configuration choice.
BTCPay outlined this deployment update in an announcement on Oct. 5, coinciding with version 2.4.5. The official GitHub release page documents the software launch on Oct. 6. For current setups, the action is triggered by the next Docker setup or update.
This update impacts Docker operators who depend on Tor—such as access through their server’s onion address—which was previously supplied through the core BTCPay Server fragment. Fragments serve as the configuration blocks utilized to build the Docker stack.
BTCPay recommends that administrators examine the deployment adjustments prior to installing updates. Following the upgrade to version 2.4.5, the command to turn on Tor is:
sudo btcpay-fragments add opt-add-tor
Tor continues to be supported, and BTCPay notes that existing data remains intact within current Tor volumes. While stored data is preserved, maintaining onion access still requires adding and executing Tor within the deployment.
Documentation for BTCPay Server explains that the optional Tor fragment opt-add-tor introduces hidden services alongside chosen onion connectivity. Operators can review configurations by running btcpay-fragments show, a command that does not alter settings but instead displays saved additional and excluded fragments alongside the effective fragments derived from the most recently generated manifest.
Commands that alter fragments demand root privileges and trigger an immediate reapplication of the setup.
Private services need separate exceptions
The release notes for version 2.4.5 additionally highlight a breaking change regarding outbound HTTP requests: destinations on private networks are now blocked by default for webhooks, invoice notification URLs, LNURL requests, and Lightning connections. This security measure aims to block server-side request forgery, or SSRF.
With this safeguard active, administrators deliberately relying on private services are required to permit necessary destinations utilizing ssrfexceptions.
The operator guide from BTCPay instructs users to restart the application and test the relevant integration following any modification to this setting.
Frequently Asked Questions
01Do I need to opt into Tor on my next BTCPay Docker update?
Yes. Operators running BTCPay Server via standard Docker must explicitly select Tor during their next setup or update to maintain onion access, as Tor is no longer automatically included.
02What command is used to enable Tor after updating to BTCPay version 2.4.5?
After updating to version 2.4.5, administrators can enable Tor using the command: sudo btcpay-fragments add opt-add-tor
03Why are private-network destinations blocked in version 2.4.5?
Outbound HTTP requests to private-network destinations are blocked by default for Lightning connections, LNURL requests, invoice notification URLs, and webhooks to prevent server-side request forgery (SSRF).
