Host a .onion site on a VPS without giving the server away

Start with what is actually different, because it is more than a strange-looking hostname. An ordinary site depends on a chain of external parties, and an onion service simply does not have that chain.

• No registrar and no registry. A v3 onion address is the base32 encoding of an ed25519 public key, plus a checksum and a version byte — fifty-six characters, generated on your own machine in a fraction of a second. Nobody sold it to you, so nobody can take it back, and there is no renewal date. That is the exact opposite of the risk model in our guide to registering a domain privately.
• No DNS. Nothing resolves a .onion name. The client asks the Tor network for a signed descriptor published under that key, so there is no resolver to poison, no zone to leak and no nameserver to take down.
• No certificate authority. The address is the public key, so the client verifies the service against the name it typed. This is what “self-authenticating” means: there is no third party vouching for identity, because identity and address are the same object.
• No inbound port. The service opens outbound circuits to a handful of introduction points and waits there. Your firewall can drop every inbound packet and the site still works. Nothing is listening on a public address, so there is nothing to scan, nothing to fingerprint and nothing to flood directly.

One historical note that still causes confusion: the old sixteen-character addresses are gone. Support for version 2 onion services was removed from Tor in October 2021, the addresses no longer work anywhere, and anything you find describing them is out of date. Everything below is v3, which is the only kind there is.

And be clear about what none of this removes. There is still a physical machine in a datacentre, a host that knows it exists, a bill somebody paid, and an application that can be broken into. Onion services move the address layer out of reach. They do not move the server.

People arrive at Tor wanting to do one of four quite different things, and the risk profiles are not remotely comparable. It is worth knowing which one you are signing up for.

• A middle relay passes encrypted traffic between other relays. It carries other people’s data, but never touches the open internet on their behalf, so it attracts no complaints.
• A bridge is an unlisted entry point for people whose access to Tor is blocked. Same traffic profile as a middle relay, with the address kept out of the public directory.
• An exit relay is where other people’s traffic leaves Tor and reaches the ordinary internet, under your IP address. This is the one that generates abuse mail and legal correspondence, and it needs deliberate handling — our Tor relay guide covers it properly.
• An onion service publishes. It carries no traffic but its own, never contacts the clearweb on anybody’s behalf, and therefore produces no abuse reports against your IP at all. There is no exit, so there is nothing to exit.

That last point is worth sitting with, because it is routinely misunderstood. Running an onion service is operationally the quietest thing you can do on the Tor network. Your server makes outbound connections that look like ordinary Tor client traffic; it never appears as the source of a connection to anyone else’s server; and the thing most people worry about — someone else’s behaviour landing on your IP — is structurally impossible.

You also do not need to run a relay in order to run an onion service, and the two are better kept apart. A relay wants bandwidth, a public ORPort and a published ContactInfo. A service wants none of those. If you want to do both, do them on two servers.

Here is the part the official documentation is thin on, and the part that actually determines whether the exercise was worth doing. Tor, configured as below, is extremely unlikely to be the thing that gives your server away. The software behind it is, because that software was written on the assumption that a web server wants to be found.

These are the channels, in roughly the order they catch people:

• The same content on the public IP. If your web server also listens on 0.0.0.0, anyone who scans the internet sees the identical page on both an IP address and an onion address. Whole-internet scanners index every open port continuously and their results are searchable by body hash and by favicon hash. One query links the two. This is the single most common way an onion service is unmasked, and it is a one-line configuration mistake.
• Server banners and default pages. A stock nginx or apache2 install answers unknown hostnames with a default page, prints its version in the Server header, and often reveals the machine’s real hostname in error output. Every one of those is a correlation handle.
• Absolute URLs. Redirects, canonical tags, sitemaps, RSS feeds, Open Graph tags and password-reset emails all love to emit a fully-qualified clearweb URL. One of them inside the onion version of a page is enough.
• Outbound requests the application makes. Analytics, web fonts, CDN assets, avatar services, map tiles, webhooks and update checks all originate from the server’s real IP, and several of them tell a third party which page was being rendered at that moment. A self-hosted site with a font loaded from someone else’s domain has an audit trail it did not intend.
• Mail. Anything the box sends stamps its real IP into the Received headers. If the service needs to send mail, that is a design problem to solve deliberately — start from our mail server guide, and assume by default that it should send nothing at all.
• Reused keys and fingerprints. The same SSH host key answering on both the public IP and an onion address links them permanently. So does the same TLS certificate, the same favicon, the same analytics identifier, or the same distinctive error page across two projects.
• Certificate Transparency. If the same box ever serves a clearweb domain over HTTPS, the certificate for that domain is written into public append-only logs forever. That names the machine, not the onion, but it names the machine.

The common shape of all of these is the same: Tor hid the address, and something else on the server published it. Step eight below is a checklist for finding them before somebody else does.

Before you install anything, answer one question, because everything downstream depends on it: is the physical location of this server a secret you are trying to keep?

There are three honest answers and they lead to genuinely different builds.

• Yes, the location is the point. Then this box does exactly one job. No clearweb site, no public DNS record pointing at its IP, no mail, no other service listening anywhere. You pay for it in a way that does not attach your name — our Monero walkthrough covers the mechanics and no-KYC accounts mean there is nothing to hand over beyond a delivery address. You keep the full three-hop configuration. Every shortcut below that trades anonymity for speed is closed to you, and that is fine, because you are not optimising for speed.
• No, the server is already public. You run an ordinary site and you want an onion address as well — for readers behind censorship, for people who would rather not resolve your domain, or because you would like to offer it. Nobody is hiding anything, so you can use a single onion service, cut the circuit from six hops to three, and advertise the address from the clearweb site with an Onion-Location header. This is a reachability feature, and it is a completely legitimate reason to be here.
• Somewhere in between. This is where most people actually are, and it is the dangerous one, because “somewhat hidden” is not a property a server can have. Pick a side. If the location genuinely matters, build it as if it matters. If it does not, stop paying the latency cost for an anonymity property you are not maintaining.

Write the answer down before you continue. Almost every mistake in this guide’s subject matter comes from building for the first case and operating as if it were the second.

If the server’s location is not a secret, running both is straightforward and genuinely useful — it is how large news organisations, Debian and several search engines offer their sites. Two mechanisms and one trade to understand.

Advertise it with Onion-Location. A single header on the clearweb site makes Tor Browser show a “.onion available” button in the address bar, and offer to switch. The header is only honoured on pages served over HTTPS, and the value must be a valid onion URL:

add_header Onion-Location "http://<your-address>.onion$request_uri" always;

There is an HTML equivalent for hosts where you cannot set headers, which has the same HTTPS requirement:

<meta http-equiv="onion-location" content="http://<your-address>.onion">

Also put the address somewhere a human can read it, in the footer or on an about page. The header only reaches people already using Tor Browser; the footer reaches everyone else.

Consider a single onion service. A normal onion connection is six hops — three from the client, three from the service — and the service’s three exist purely to hide where it is. If that is not a secret, you can drop them. The latency improvement is large and immediately noticeable. The configuration is blunt on purpose:

# /etc/tor/torrc — these are INSTANCE-WIDE, not per service
HiddenServiceNonAnonymousMode 1
HiddenServiceSingleHopMode 1
SOCKSPort 0

Both options are required together, the SOCKS port must be disabled, and they apply to every onion service on that Tor instance — there is no per-service opt-out. Tor will refuse to start if you set one without the others, which is the software doing you a favour. If a single instance hosts one service whose location is public and another whose location is not, run two instances, or better, two servers.

And accept the trade. Publishing both addresses declares that the same operator runs both, and serving identical content from both makes them trivially linkable regardless. That is the deal, and for a public site it costs nothing. Keep the hygiene anyway: no absolute clearweb URLs inside the onion version, cookies scoped per host so a session does not travel between them, and a content security policy that does not pull assets across.

By default, anyone who knows your address can reach the service. Client authorization changes that at the network layer rather than the application layer, and the difference matters more than it sounds.

With authorization enabled, the descriptor your service publishes is encrypted to a set of client keys. A visitor without one of those keys cannot decrypt it, cannot learn the introduction points, and therefore cannot connect at all — they do not reach a login page, they do not get a refusal, they get nothing. The service is not unlisted; it is invisible.

Generate an x25519 keypair per client. Every tool here is already on a Debian box:

openssl genpkey -algorithm x25519 -out alice.prv.pem

# private key — goes to the client, never to the server
grep -v 'PRIVATE KEY' alice.prv.pem | base64 -d | tail -c 32 | base32 | tr -d '='

# public key — goes on the server
openssl pkey -in alice.prv.pem -pubout | grep -v 'PUBLIC KEY' \
  | base64 -d | tail -c 32 | base32 | tr -d '='

On the server, drop the public key into an authorized_clients directory inside the service directory. The filename is arbitrary as long as it ends in .auth, which makes revocation a matter of deleting one file:

mkdir -p /var/lib/tor/onion-site/authorized_clients
echo "descriptor:x25519:<ALICE-PUBLIC-KEY>" \
  > /var/lib/tor/onion-site/authorized_clients/alice.auth
chown -R debian-tor:debian-tor /var/lib/tor/onion-site
systemctl reload tor@default

On the client, the private key goes in the directory named by ClientOnionAuthDir, in a file ending .auth_private, with the address repeated inside it. Tor Browser has its own directory for these under its data folder, and will prompt for a key if it hits a service that needs one:

# /var/lib/tor/onion-auth/mysite.auth_private
<address-without-the-.onion>:descriptor:x25519:<ALICE-PRIVATE-KEY>

This is the right tool for a staging site, an admin panel, a private file drop, or a self-hosted Nextcloud that only you use — anything where the honest answer to “who should be able to see that this exists?” is “nobody but us”. The cost is real and it is administrative: you have to get keys to people over a channel you trust, and you have to remember to remove them afterwards.

Onion services fail in their own particular ways, and none of them look like an ordinary outage. Four things are worth setting up before you need them.

Denial of service is the real operational problem. Because there is no IP address to filter, the usual defences do not apply, and a determined flood of introduction requests is cheap to send. Tor has two answers, both set per service in torrc: HiddenServiceEnableIntroDoSDefense 1 rate-limits requests at the introduction points, and HiddenServicePoWDefensesEnabled 1 makes clients solve a small proof-of-work puzzle that gets harder under load, so legitimate visitors wait a moment while a flood becomes expensive. Turn both on from the start; the cost when nothing is attacking you is negligible.

Keep the clock right. Descriptors are published and looked up against time periods derived from a shared network value. A server whose clock has drifted badly publishes to the wrong place and becomes unreachable while appearing perfectly healthy in its own logs. Make sure an NTP client is running, keep the machine on UTC, and check it when a service mysteriously stops resolving.

Monitoring has to go through Tor. No commercial uptime service can probe a .onion address, which means the usual answer is unavailable to you. Run the check yourself from a second machine that is not the one hosting the service — a cron job doing torsocks curl -s --max-time 60 against a known URL, comparing the output to a known string, is enough and costs nothing.

Plan for more than one instance if uptime matters. OnionBalance lets several backend servers share a single onion address: a front-end instance holds the key that owns the address and publishes a descriptor pointing at the introduction points of the backends, so you get load distribution and failover without the address ever changing. It is more moving parts than most sites need, but it is the supported answer, and it is worth knowing that it exists before you have painted yourself into a single box.

One last operational habit: restarting Tor takes the service offline for a few seconds while it republishes, and a reinstall that wipes /var/lib/tor takes it offline forever. Treat that directory the way you would treat a private key, because it is one.

An onion address removes the registrar, the resolver, the certificate authority and the open port. It does not remove anything else, and being precise about the remainder is what separates a useful tool from a false sense of safety.

It does not fix the application. A vulnerable web app behind an onion service is a vulnerable web app; the first thing many attackers do after getting code execution is make an outbound request that reveals the server’s real address. Give the box the ten-minute pass in our Debian hardening guide, keep it patched, and treat it as exposed even though nothing is listening.

It does not hide the server from the people who run it. We know a server exists, when it was deployed, and what its IP address is, because we are the ones who allocated it. That is true of every host, everywhere, and anyone telling you otherwise is selling something. What we can say precisely is what we do with it, which is set out in our honest account of what a crypto-paid VPS hides.

It does not defeat a patient, well-resourced adversary on its own. Traffic volume and timing are visible at the edges of the network, and a service that goes quiet whenever a particular person is asleep is telling you something. Nor does it help if the content identifies you: the same writing style, the same PGP key, the same avatar or the same forum handle as a public identity closes the loop no matter how good the transport is.

On our own side, so you can calibrate: onion services are welcome on every tier and need nothing special from us, because they open no ports and generate no abuse traffic. We run no-KYC accounts that need only an address to deliver credentials to. We treat routine copyright correspondence as an operational matter rather than an automatic takedown, we act on valid court orders in the jurisdiction the server sits in, and the hard floor is absolute and applies here exactly as everywhere else: no CSAM, no terrorism content, no exceptions. Read the acceptable-use policy and how we handle abuse reports before you build something you would be unhappy to move. Our Tor-friendly VPS page has the tier guidance.