Operators running BTCPay Server, the self-hosted Bitcoin payment software, through its standard Docker deployment must explicitly select Tor at their next setup or update if they want to retain onion access. The change, introduced with version 2.4.5, removes Tor from the automatically included components, turning a previously bundled service into an administrator's configuration choice.

BTCPay detailed the deployment change in an announcement dated Oct. 5 that accompanied version 2.4.5, while the official GitHub release page records the software release on Oct. 6. For existing installations, the relevant trigger is their next Docker setup or update — meaning the component can fall out of a running deployment as part of routine maintenance unless the operator opts back in.

The adjustment is significant for Docker operators who rely on Tor, including access through their server's onion address — the .onion endpoint exposed by Tor's hidden services — and who previously received the service through the core BTay Server fragment. Fragments are the configuration components used to assemble the Docker stack.

Re-enabling Tor after the update

BTCPay advises administrators to review the deployment changes before updating. Once on version 2.4.5, the instruction for enabling Tor is:

sudo btcpay-fragments add opt-add-tor

Tor remains supported, and BTCPay says existing data stays in the current Tor volumes. That preserves stored data, though continued onion access still depends on including and running Tor in the deployment.

According to BTCPay Server documentation, the optional Tor fragment opt-add-tor adds hidden services and selected onion connectivity. Operators can inspect their configuration using btcpay-fragments show, a command that does not change anything and reports saved additional and excluded fragments alongside the effective fragments from the last generated manifest. Checking that output before the update, and again after adding the fragment, gives administrators a before-and-after record of what their stack is actually running. Commands that alter fragments require root privileges and reapply the setup immediately.

Private services need separate exceptions

The 2.4.5 release notes also identify a breaking change for outbound HTTP requests: private-network destinations are blocked by default for Lightning connections, LNURL requests, invoice notification URLs and webhooks. The restriction is intended to prevent server-side request forgery (SSRF), a class of vulnerability in which an application is tricked into sending requests to internal or otherwise restricted network resources.

Because both changes ship in the same release, a single update can touch two separate parts of an operator's setup: onion availability and outbound calls to private addresses. With that protection enabled, operators who intentionally use private services must allow the required destinations through ssrfexceptions. BTCPay's operator guide says to restart the application and exercise the affected integration after changing the setting.