Operators running the popular open-source Bitcoin payment processor BTCPay Server via its standard Docker deployment must take deliberate action during their next setup or update cycle if they wish to maintain uninterrupted onion network access. The software maintainers have altered how the platform handles Tor integration, decoupling the privacy-enhancing networking tool from the core bundle and shifting it into an optional configuration choice for system administrators.
The adjustment was formally outlined by the BTCPay development team in an announcement published on Oct. 5, accompanying the rollout of software version 2.4.5. Official logs on the project’s GitHub release page further document the software’s availability starting Oct. 6. For existing self-hosted installations, the shift does not immediately disrupt active configurations, but it becomes a critical consideration during the next scheduled Docker setup or update process.
This architectural change carries distinct implications for Docker-based operators who rely on Tor to route traffic securely, particularly those who access their financial management backends through dedicated onion addresses. Previously, Tor came pre-packaged as an inherent component of the core BTCPay Server fragment—the modular configuration blocks used to assemble and orchestrate the platform’s underlying Docker containers. By removing Tor from these automatically included components, the project is placing the responsibility of selection directly onto the shoulders of the system administrator.
To assist operators through this transition, project maintainers have advised administrators to carefully review all deployment modifications before initiating an update. For those running the updated version 2.4.5 who wish to continue utilizing Tor, the required configuration command involves adding the optional fragment back into the deployment manifest via the terminal command line using sudo btcpay-fragments add opt-add-tor.
Despite the change in deployment mechanics, Tor itself remains fully supported by the software ecosystem. BTCPay has explicitly confirmed that existing Tor data will be preserved safely within current Tor storage volumes during the transition. While stored data remains intact, administrators must understand that continued onion routing functionality is no longer automatic; it strictly depends on explicitly including and executing Tor within the updated deployment stack.
According to official BTCPay Server system documentation, the optional Tor fragment, designated as opt-add-tor, is engineered to provision hidden services and facilitate specific onion network connectivity. Administrators seeking to audit their current deployment states can utilize the diagnostic command btcpay-fragments show. This inspection utility is designed to report saved additional fragments, excluded modules, and the effective fragments derived from the most recently generated configuration manifest without making any active alterations to the underlying setup. Because any command that modifies container fragments forces an immediate reapplication of the system setup, operators are required to execute these administrative tasks with root privileges.
Private Services Need Separate Exceptions
Alongside the changes to Tor deployment, the release notes for version 2.4.5 introduce another crucial security-related modification that impacts outbound HTTP requests across the network stack. Specifically, private-network destinations are now blocked by default for a variety of critical operations, including Lightning Network connections, LNURL requests, invoice notification URLs, and incoming or outgoing webhooks.
This restrictive measure has been implemented to fortify the software against Server-Side Request Forgery, commonly known as SSRF vulnerabilities, which can otherwise allow malicious entities to exploit server infrastructure by forcing it to interact with internal or private network resources. While this default security posture enhances the overall safety profile of the payment gateway for the vast majority of users, it introduces a necessary hurdle for operators who intentionally run integrated private services.
Administrators whose specific routing architectures or local node setups rely on communicating with private-network destinations must explicitly permit these necessary connections by configuring custom exceptions through the platform’s ssrfexceptions parameters. In accordance with the official BTCPay operator guidelines, after modifying these exception settings, administrators are required to restart the application and thoroughly test the affected payment integrations to ensure smooth operational continuity.
