Onion-Location Header for Automatic .onion Redirects

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.

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.

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 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.