Onion-Location Header for Automatic .onion Redirects
The Onion-Location HTTP header tells Tor Browser that your website has a .onion mirror available, prompting users to switch to the more private hidden service version. When Tor Browser detects this header, it displays a purple badge in the address bar offering to redirect the user to your .onion address. This is the standard mechanism used by major websites like the BBC, ProPublica, and DuckDuckGo to offer .onion alternatives.
Need this done for your project?
We implement, you ship. Async, documented, done in days.
How the Onion-Location Header Works
The Onion-Location header is a standard HTTP response header that contains the .onion URL equivalent of the current page. When Tor Browser receives this header, it displays a ".onion available" badge in the address bar. Clicking this badge navigates the user to your hidden service, where all subsequent requests benefit from full Tor end-to-end encryption.
The header format is simple: Onion-Location: http://your56charaddress.onion/current/path. It should map the exact page the user is viewing on the clearnet to the equivalent page on your .onion site. This ensures a seamless transition — the user lands on the same content, just served through Tor's hidden service protocol.
Only Tor Browser responds to this header. Regular browsers ignore it entirely, so adding it has zero impact on non-Tor visitors. It is also the recommended approach over meta tag alternatives because it works before the page body is parsed, enabling faster redirects.
Nginx Configuration for Onion-Location
Add the Onion-Location header to your clearnet Nginx server configuration. The header should dynamically include the current request URI:
# /etc/nginx/sites-available/clearnet-site
server {
listen 443 ssl http2;
server_name example.com;
# Add Onion-Location header to all responses
add_header Onion-Location http://your56charv3onionaddress.onion$request_uri always;
# Your existing configuration
root /var/www/html;
index index.html;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
location / {
try_files $uri $uri/ =404;
}
}The $request_uri variable ensures that every page maps correctly. A visitor on https://example.com/about will be offered http://your56char.onion/about. The always parameter ensures the header is sent even on error pages.
For sites behind a reverse proxy or CDN, make sure the Onion-Location header is not stripped by intermediate proxies. Some CDNs filter unknown headers by default.
Apache and HTML Meta Tag Alternatives
For Apache servers, add the header in your VirtualHost or .htaccess configuration:
# Apache VirtualHost configuration
ServerName example.com
Header always set Onion-Location "http://your56charv3onionaddress.onion%{REQUEST_URI}e"
# Or via .htaccess
Header always set Onion-Location "http://your56charv3onionaddress.onion%{REQUEST_URI}e"If you cannot modify HTTP headers (for example, on a static hosting platform), use the HTML meta tag alternative in your page's <head>:
<!-- HTML meta tag alternative -->
<head>
<meta http-equiv="onion-location"
content="http://your56charv3onionaddress.onion/current-page" />
</head>The meta tag approach is less efficient because the browser must download and parse the HTML before discovering the .onion alternative, while the HTTP header is processed immediately upon receiving the response headers. Use the header approach whenever possible.
AnubizHost — Dual-Stack Clearnet + Onion Hosting
AnubizHost supports dual-stack hosting where your website is available on both the clearnet and as a .onion hidden service. We pre-configure the Onion-Location header on your clearnet site so Tor Browser users are automatically offered the privacy-enhanced .onion version.
Our offshore servers in Iceland, Romania, and Finland serve both clearnet and Tor traffic from the same infrastructure. Pay with Bitcoin, Monero, or other cryptocurrencies — no KYC, no identity verification. Whether you need a clearnet site with an .onion mirror or a Tor-only hidden service, AnubizHost provides the hosting and configuration to make it happen seamlessly.
Related Services
Why Anubiz Labs
Ready to get started?
Skip the research. Tell us what you need, and we'll scope it, implement it, and hand it back — fully documented and production-ready.