The address is the easy part#
If you’ve never set up an onion service, it can sound like a serious technical job. It isn’t. On a server that already runs a website, the Tor Project’s setup guide gets you a working onion address with two lines of configuration and a restart of Tor. A capable system administrator can do it before lunch.
That’s exactly why organisations get it wrong. Because the technical step is so quick, it’s easy to treat an onion service as a small IT job and forget that you’ve just created something with very unusual properties. Its address is a cryptographic key, and as far as the world can tell, whoever holds that key is you. If it’s stolen, there’s no registrar to call, no way to transfer it, and no way to change it without telling everyone a new address. And because nobody can read the address and know it’s yours, the whole value of the service depends on how well you tell people it’s genuine.
So this guide is organised around decisions rather than commands. Five of them, roughly in the order you’ll face them.
- What kind of onion service are you running? A mirror of your public site, an onion-only service, an internal service for staff, or something else.
- Who holds the key? And how do you set it up so that the answer stays true.
- How will people know it’s yours? The single biggest factor in whether an onion service helps or harms the people using it.
- How will it cope under pressure? Attacks, sudden traffic and security updates.
- What happens when things change? Address changes, a compromised key and, eventually, retirement.
It finishes with a checklist you can hand to whoever will run the service. If you’re new to how onion services work, read What Is an Onion Service? first. It explains why the address is a key, which everything here builds on.
Why do this at all? Because the people who most need to reach you safely are often the ones least able to do it on the ordinary web. Readers in censored countries, sources contacting journalists, people who don’t want their visit to your site to be visible to their internet provider. An onion service lets them reach you without leaving Tor, and without either side having to trust an exit relay. The Tor Project’s onion services team has written about how many organisations now show a purple “.onion available” button to Tor Browser users for exactly that reason.
Decision one: what kind of onion service?#
“An onion service” covers several quite different things. Choosing the right one first saves you from building the wrong protections, or the wrong number of them.
| What you’re building | When it fits | The key trade-off |
|---|---|---|
| An onion mirror of your public website | You already have a public site and want Tor users to reach it safely | Easy and low-risk. Your organisation and server are public anyway |
| A single onion service | Your server’s location doesn’t need to be hidden, and you want speed | Faster, but the server makes no attempt to stay anonymous |
| An onion-only service | The server’s location itself must stay hidden | Much harder. Every detail of the server can give it away |
| A private service for staff | Internal tools that only certain people should reach | Uses client authorisation, so outsiders can’t even connect |
| A whistleblowing drop | Receiving documents from sources | Don’t build this yourself. Use SecureDrop |
Mirrors of public sites#
This is what most organisations want, and it’s what the newsrooms, search engines and nonprofits in our Official Onion Mirrors Directory mostly run. Good examples include the services in Search Engines With Official Onion Sites, the email providers in Secure Email Over Tor, and the Tor Project’s own onion sites. Your organisation is already public, so the goal isn’t to hide the server. It’s to give Tor users a route that never leaves the Tor network, and to make it hard for anyone to impersonate you.
Single onion services#
An ordinary onion service hides both ends, so a connection between a visitor and the service passes through six relays in total. If your server’s location isn’t secret, half of that is unnecessary. The Tor Project’s glossary describes a single onion service as one for services that don’t need anonymity themselves but want to offer it to their visitors, using three hops instead of six. Visitors are just as protected, and the connection is faster. Large public organisations often choose this. The settings are covered in the Tor Project’s advanced onion service documentation, and you should only use them when you’re sure the server’s location doesn’t need protecting. Organisations that already use a content delivery network may also find their provider offers onion routing, as Cloudflare has described for its customers.
Onion-only services#
Some organisations, such as activist groups in hostile countries, need the server itself to stay hidden. That’s possible, but it’s a different level of work. A web server can reveal its real address in error pages, headers, software versions, outbound connections and many other small ways. The Tor Project’s operational security guide and Riseup’s onion services best practices are the place to start, and if this is your situation, get experienced help.
Private services for staff#
Onion services can require client authorisation, so that only people holding a particular key can connect at all. To everyone else, the address simply doesn’t work. That’s useful for internal tools, admin panels or file sharing within a small team. The Tor Project’s client authorisation guide explains how.
Whistleblowing#
If you want sources to send you documents, use SecureDrop, which is built, audited and maintained for exactly that. We cover it in News Onion Sites: BBC, DW, The Guardian and SecureDrop. A home-made upload form on an onion address is not a substitute.
For a very simple case, such as sharing a few static files, OnionShare can publish an onion site from a desktop app with almost no configuration. It’s great for small, temporary jobs, but it isn’t designed for an organisation’s permanent public presence.
Decision two: who holds the key?#
An onion address isn’t registered anywhere. It’s derived from a cryptographic key that Tor generates on your server, and the address is that key, written out. That has three consequences most organisations haven’t faced before.
- Whoever has the key can be you. The Tor Project’s setup guide is blunt about it. If your keys leak, other people can impersonate your onion service, making it compromised, useless and dangerous to visit.
- Nobody can give it back. There’s no registrar, no support line and no recovery process. If you lose the key with no backup, the address is gone for good.
- You can’t change it quietly. A new key means a new address, and every place you’ve published the old one has to be updated.
So before anyone types a configuration line, decide who owns this. In practice, that means a short written answer to a few questions.
| Question | A sensible answer |
|---|---|
| Who can access the key? | Two or three named people, no more |
| Where is it backed up? | Encrypted, offline, in at least two separate places |
| Where must it never go? | Tickets, chat, email, shared drives or code repositories |
| One key or several? | One per service, and separate keys for testing and production |
| Who approves using it somewhere new? | A named owner, usually the same person who owns your web domain |
It helps to treat the onion key the way you’d treat the private key for your organisation’s TLS certificate, or the password to your domain registrar. It’s that important, and in one way more so, because there’s no authority above it.
Do you want a recognisable address?#
By default, the address is 56 random-looking characters. Some organisations keep generating keys until they find one whose address starts with something recognisable, like their name. The Tor Project’s Onionmine tool helps organise that, along with TLS certificates. A recognisable start helps people notice when they’re in the right place.
But don’t rely on it. Attackers can generate addresses with the same first few characters too, which is exactly how phishing clones work, as we explain in Onion Phishing: How Fake Mirrors Clone Real Addresses. A memorable prefix is a convenience, not a security feature. And if you do generate one, do it on a computer you trust, because the tool is creating your secret key.
The basic setup#
With the decisions made, the technical part really is short. These are the steps from the Tor Project’s setup guide, in brief.
- Run a separate web server instance for the onion site, listening only on the local machine, so the onion version isn’t accidentally exposed or mixed up with your public site.
- Add the onion service to Tor’s configuration file, usually called torrc.
- Restart Tor. It creates the service directory and generates the keys.
- Find your address in the file called hostname in that directory, and test it in Tor Browser.
The configuration itself is two lines.
HiddenServiceDir /var/lib/tor/my-website/
HiddenServicePort 80 127.0.0.1:80The first line tells Tor where to keep the service’s keys. The second says that visitors connecting to port 80 of your onion address should be passed to the web server on the same machine. The Tor Project also suggests using a local Unix socket instead of a network port, which avoids accidentally exposing the onion service to the local network.
HiddenServiceDir /var/lib/tor/my-website/
HiddenServicePort 80 unix:/var/run/tor/my-website.sockEverything in that service directory other than the hostname file is key material. Back it up according to the policy above, and nowhere else.
If you manage many servers, the same guide points to tools for automating this with Docker, Ansible or Terraform. And if you’re curious about the future, Tor’s newer implementation, Arti, can also host onion services, as we explain in Arti 2.7.0: Tor’s Rust Rewrite Explained. For a production service today, most organisations still use the standard C version of Tor.
Decision three: how will people know it’s yours?#
This is the decision that matters most to the people you’re serving, and the one organisations most often skip. Nobody can look at a 56-character address and tell who it belongs to. If you publish your onion address in only one place, or only in a screenshot, you leave a gap that phishing sites are happy to fill. Our guide How to Verify an Onion Address Is Official explains how careful users check an address. Your job is to make every one of those checks easy to pass.
| What you publish | What it proves to visitors | Effort |
|---|---|---|
| The address on your main website | The organisation that controls your domain also announces this onion | Low |
| An Onion-Location header | Tor Browser shows a “.onion available” button on your site that leads to the right address | Low |
| A TLS certificate that includes the onion address | A certificate authority has checked that the onion and your domain belong together | Medium |
| Announcements on your official channels | The same address is consistent everywhere you speak publicly | Low |
| A landing page explaining how to use it | Visitors know what to expect and where to find Tor Browser | Low to medium |
Publish it on your own site#
Put the full address, in text, on a page of your ordinary website that people can find, such as your contact or security page. Text matters, because people need to compare it character by character. A short explanation of what the onion address is for helps too.
Add Onion-Location#
The Onion-Location header tells Tor Browser that your website has an onion version. When a Tor Browser user visits your normal site, a purple “.onion available” button appears, and clicking it takes them to the right address. Because the header comes from your own website, the link it gives is as trustworthy as your website itself. For many organisations, this is the single most useful thing they can do. It’s usually one line in your web server’s configuration, sending a header like this with each page.
Onion-Location: http://youronionaddress.onionReplace the placeholder with your full address.
Consider a certificate that names the onion#
Onion addresses already provide encryption and prove which server you’ve reached, so HTTPS isn’t strictly necessary. But a TLS certificate that covers both your ordinary domain and your onion address is a strong extra signal, because a certificate authority has checked that the two belong to the same organisation. Some commercial certificate authorities issue them. A standard for automating this, RFC 9799, was published in June 2025, but as of October 2026, no major free certificate authority was issuing onion certificates automatically. Research projects such as Sauteed Onions are exploring other ways to tie onion addresses to domain names through certificates.
Say it consistently#
Announce the address on your official social accounts, in your newsletters and anywhere else you speak publicly, always as the full address. If you sign announcements, for example with a PGP key you already publish, sign this one too.
Help people find their way#
Many of the people you want to reach have never used Tor. The Tor Project’s Onion Launchpad is a ready-made landing page you can customise, explaining how to download Tor Browser, connect and reach your onion address, translated into more than 60 languages. You can also point new users to our guide How to Download and Install Tor Browser Safely.
Tell directories, carefully#
Once your address is published on your own site, independent directories can check it and list it. We list official services in our Official Onion Mirrors Directory, each with a link to the page where its owner publishes the address, and you can tell us about yours. The right order is your own site first, directories second. A directory listing should point back to your announcement, never replace it. And be wary of anonymous link lists that offer to list you for a fee, for the reasons we explain in Why Most ‘Hidden Wiki’ Lists Are Full of Scams.
Decision four: how will it cope under pressure?#
Launching an onion service is the start, not the finish. Popular services attract attacks, traffic grows, and Tor itself gets security updates that you have to apply. Plan for all three.
Turn on the proof-of-work defence#
Onion services have been a target for denial-of-service attacks, where an attacker floods a service with connection attempts until ordinary visitors can’t get through. Since Tor 0.4.8, onion services have a built-in defence. The Tor Project’s introduction to it describes it as dormant in normal conditions. When a service is under stress, visitors’ Tor Browsers are asked to solve a small computational puzzle before connecting, and the service prioritises those who did the work. Ordinary visitors barely notice. Attackers making huge numbers of connections find it expensive.
You switch it on per service, with one line under that service’s configuration.
HiddenServicePoWDefensesEnabled 1There are further settings for tuning how much traffic is let through, and the Tor Project’s PoW FAQ explains when and how to adjust them. For an organisation’s public onion site, there’s little reason not to enable it.
Plan for scale and redundancy#
A single Tor process on a single server is a single point of failure. For a busy or important service, the Tor Project’s onion services team maintains tools for spreading the load. Onionbalance lets several back-end servers share one onion address, so that if one fails, the others keep answering. Oniongroove builds on it to help deploy and monitor that kind of setup. Both are listed in the Tor Project’s onion services documentation.
Keep Tor updated, and restart it#
Tor’s security releases matter more to you than to most users, because your service accepts connections from strangers all day. September 2026 is a good example. Tor 0.4.9.13 included three separate fixes for onion services, covering how their circuits keep activity separate, rendezvous circuits and introduction points. We explain them in Tor’s September 2026 Security Fixes. Install updates from the Tor Project’s own package repository where you can, and remember that an update doesn’t help until Tor is restarted.
Keep the onion version self-contained#
One of the commonest mistakes is serving an onion version of a site that still loads fonts, scripts, images or analytics from ordinary web addresses. Every one of those is a request that leaves the Tor network, slows the page, and may tell a third party that someone is reading your onion site. It can also break the page for visitors using Tor Browser’s Safest security level, which blocks JavaScript. Serve everything from the onion itself, avoid third-party trackers entirely, and test the site at Safest before you launch.
Watch it, and log less#
Set up a simple monitor that regularly loads your onion address through Tor from somewhere outside your own network, and alerts someone when it fails. Onion services can go quietly offline in ways your ordinary monitoring won’t notice.
At the same time, think about what you log. People who choose your onion address are telling you they care about privacy. Log what you need to run the service, keep it for as short a time as you can, and don’t add tracking you’d hesitate to explain to them. For onion-only services that must hide their location, tools such as OnionScan can check whether the server is leaking information about itself.
Decision five: what happens when things change?#
Websites change domains, get hacked and eventually close down. Onion services do too, but each of those events works differently, because the address is a key and there’s no authority to appeal to. It’s much easier to decide how you’ll handle them before they happen.
A planned address change#
Sometimes you’ll want a new address, for example to move to a recognisable one, or to separate services that started out together. Do it in the open.
- Announce the new address on your website and official channels before switching.
- Run the old and new addresses side by side for a while.
- Update your Onion-Location header to the new address.
- Replace the old onion site’s content with a notice pointing to the new one, rather than shutting it off without warning.
- Tell the directories that list you, so they can update.
A leaked or stolen key#
This is the scenario to plan for most carefully, because there’s no way to revoke an onion address. If someone else has your key, they can run a service at your address, and visitors’ browsers will accept it as genuine.
- Treat it as a security incident. Work out how the key leaked, and close that gap first.
- Stop using the old address and generate a new key on a clean system.
- Announce the change loudly, on your website and every official channel, explaining that the old address can no longer be trusted. Be specific, because some people will still have the old one bookmarked.
- Update everything that points to you, including your Onion-Location header, certificates, landing pages and directory listings. You can report the change to us so we can update our directory.
- Keep the warning up for a long time. The old address may keep working for whoever has the key, so your warning is the only protection your visitors have.
Retiring a service#
When you no longer need an onion service, retire it deliberately.
- Announce the date in advance.
- Remove the Onion-Location header from your website.
- Leave a notice at the onion address for a while, saying the service has closed and where to go instead.
- Shut it down, and decide what to do with the key. If you’ll never use the address again, securely destroy the key and all its backups, so it can’t be misused if an old backup ever leaks.
A launch checklist#
Hand this to whoever will run the service.
- Decide what kind of onion service you need, and write down why.
- Name the key’s owners, no more than two or three people.
- Agree where encrypted, offline backups of the key will be kept.
- Run a separate web server instance for the onion site, listening only locally or on a Unix socket.
- Configure the service in torrc, restart Tor and test the address in Tor Browser.
- Make sure the onion site loads nothing from the ordinary web, and test it at the Safest security level.
- Enable the proof-of-work defence.
- Publish the full address in text on your own website.
- Add the Onion-Location header.
- Announce the address on your official channels, and consider a landing page.
- Set up monitoring through Tor from outside your network.
- Subscribe to Tor security announcements, and agree who applies updates and restarts Tor.
- Write down your plan for a leaked key before you need it.
If any step is beyond your team, the Tor Project has offered direct help. In 2022 it set up an Onion Support group that has deployed onion services for organisations and supported others with their own deployments, as described in its blog post on the work. The tor-onions mailing list is also where operators help each other.
Where to go next#
- New to how onion services work? Read What Is an Onion Service?
- Want to see how visitors will check your address? Read How to Verify an Onion Address Is Official.
- Want examples of organisations doing this well? Browse the Official Onion Mirrors Directory and News Onion Sites.
- Keeping your Tor up to date? See Tor’s September 2026 Security Fixes: What to Update.
- Want to understand the threat you’re defending against? Read Onion Phishing: How Fake Mirrors Clone Real Addresses.
- Wondering about the legal side of running a service? Read Is Tor Legal? Using Onion Services Responsibly.
- Want your visitors to be able to reach you even where Tor is blocked? Point them to Bridges, Snowflake and WebTunnel.
Sources#
- Set up Your Onion Service, Tor Project community portal
- Onion services advanced settings, Tor Project, including Onion-Location, client authorisation and operational security
- Single onion service, Tor Project glossary
- Introducing Proof-of-Work Defense for Onion Services, Tor Project blog, 2023
- PoW FAQ, Tor Project onion support wiki
- Onion Services Ecosystem documentation, Tor Project, including Onionbalance, Oniongroove, Onionmine and Onion Launchpad
- Reflecting on how we plant and grow onions, Tor Project blog
- Onion services best practices, Riseup
- RFC 9799, on automated certificates for onion addresses, June 2025