The Onion-Location Header: How Clearnet Sites Point the Way to Their Onions
Onion addresses are long, random and effectively impossible to guess. In late 2019, the Tor Project proposed an elegant fix: a single HTTP header that lets a regular website quietly tell Tor users where its hidden twin lives. The idea was simple. The rollout has been anything but.
A header born from a discovery problem
The proposal, filed as document 100 in the Tor Browser specification repository, defined an Onion-Location response header (tor-browser-spec). A clearnet site serves its pages as usual but adds one line pointing to the matching .onion URL. No redirects, no banners, no clutter. The rules were deliberately strict. The header value must be a valid http or https URL with a .onion hostname, the page must be served over HTTPS, and the page itself must not already be an onion site. Operators can set it in Apache, nginx or Caddy, or fall back to an HTML meta tag when they cannot touch server config, as the official deployment guide details (Tor Project community docs).How browsers handle the prompt
The mechanism shipped in Tor Browser 9.5 in June 2020 (Tor Project blog). When the browser receives the header, a purple pill reading '.onion available' appears in the address bar. Clicking it takes the user to the same page on the hidden service, path intact. On first encounter, the browser asks whether the user wants to prioritize .onion sites automatically whenever one is known. Say yes once, and future hops happen silently. Brave later implemented compatible behavior, and OnionBrowser on iOS followed, giving the header reach beyond the Tor Project's own client.Who switched on the light
Major publishers had been running onion mirrors for years before the standard existed. ProPublica went dark-web-first in 2016, the New York Times followed in 2017, and Facebook opened facebookcorewwwi.onion back in 2014. The BBC joined in October 2019, citing readers in China, Iran and Vietnam where its coverage is blocked (BBC News). Alec Muffett, the engineer who helped both the BBC and the Times stand up their mirrors, argued that each new onion address improves speed and cryptographically guarantees a site cannot be faked. Today the Guardian, Deutsche Welle and the Internet Archive all send the header, letting Tor users reach them without ever touching an exit node.Why adoption stalled
The numbers never matched the ambition. Security researcher Daniel Aleksandersen crawled the top one million domains shortly after launch and found just thirty sites issuing the header, none of them named BBC, New York Times or Facebook (Ctrl blog).The header solves discovery, but nothing forces a site to maintain two parallel production environments forever.The structural reasons are mundane. Only a small sliver of visitors browse through Tor, so most operators see little return on the operational burden. Onion services need keys, monitoring and incident response like any other infrastructure. And because mainstream browsers ignore the header entirely, the audience cap is hard-baked into the ecosystem. There is also an asymmetry problem: some flagship adopters still rely on footers and press releases rather than the header, so even well-run mirrors stay invisible unless users know where to look. That is precisely why onion discovery through search engines and directories continues to matter alongside any header-based approach.