Knowledgebase / Onion Addresses / How to create a vanity v3 onion address

How to create a vanity v3 onion address

A v3 onion address is not chosen, it is found: it is the base32 of the service's ed25519 public key, so the only way to get an address starting with a word you like is to generate key pairs until one of them happens to match. This guide builds a generator, runs it, and shows what the resulting key files are — on Linux, macOS or Windows (WSL).

Step 1 — Install the generator

mkp224o is the current tool for this. It needs a C compiler, autotools and libsodium:

# Debian / Ubuntu / WSL
sudo apt install -y git gcc make autoconf automake libtool libsodium-dev

# macOS (Homebrew)
brew install autoconf automake libtool libsodium

git clone https://github.com/cathugger/mkp224o
cd mkp224o
./autogen.sh && ./configure && make

On Windows the shortest path is WSL: install Ubuntu from the Microsoft Store and run the Debian commands above inside it. A native Windows build works too, but you would have to compile libsodium with MSVC first.

Step 2 — Run it

The first argument is the filter — the text the address must start with. Give it a directory for the keys and the number of addresses you want:

./mkp224o -d keys -n 4 ddw
mkp224o running in a terminal: it lists four generated onion addresses that all start with ddw, then shows the three key files created for each

Each hit prints the full address and mkp224o writes a directory named after it, containing exactly the three files a Tor daemon expects:

  • hostname — the address, with a trailing newline (this is what you copy)
  • hs_ed25519_public_key — the public key
  • hs_ed25519_secret_key — the private key; whoever holds it is that onion service

The filter is case-insensitive and works on the base32 alphabet (a-z and 2-7), so ddw matches ddw…, and -n 1 stops after the first hit. -t N sets the thread count; without it mkp224o uses every core.

Step 3 — Understand what it costs

Every extra character multiplies the work by 32, because 32 is the size of the base32 alphabet. Measured on 4 threads for this guide: a 3-character filter finished in seconds. Expect roughly:

  • 3 characters — seconds
  • 4 characters — a minute or two
  • 5 characters — around an hour
  • 6 characters — a day or more
  • 7 characters or more — weeks; not worth it

Those numbers are why nobody has a facebook… onion address. A short prefix plus a memorable case pattern is the practical limit; if you need a human-readable name, use an onion address alias or a clearnet domain instead of a longer prefix.

On Windows

You do not need a Linux machine for this. The mkp224o author publishes the built binary, so the shortest route is to download the release archive for Windows from the releases page, unpack it, and run it from the command prompt in that folder:

cd C:\Users\you\Downloads\mkp224o-1.3.0\bin
mkp224o.exe -d keys -n 1 foo

Everything else is the same as on Linux: -d is the output directory, -n the number of addresses to keep, the filter is the prefix, and the keys land in keys\<address>\. Because Windows has no separate build step here, the older Cygwin + Eschalot instructions only matter if you still need a v2 address — Eschalot predates v3 and cannot produce one. If you do want to compile mkp224o yourself, Cygwin or WSL2 both work with the commands from Step 1.

Step 4 — Keep the key safe

The secret key is the service. Back up the whole directory, keep it 0600, and never upload it to a chat, an issue tracker or a "vanity address generator" website — a hosted generator can keep a copy of the key it just produced for you, which hands it your service forever.

chmod 600 keys/*/hs_ed25519_secret_key
tar czf vanity-keys-backup.tar.gz keys

Step 5 — Install it on a hosted onion service

Generating the key is half the job; the service has to run it. Open your onion service in the Customer Portal, choose the Onion Addresses tab, and click Create a New Onion Address. The card offers three ways to get one:

  1. Create an onion address by specifying character(s) — you type the prefix and we do the search. The limit is four characters (a-z and 2-7 only), which is exactly the range that finishes in seconds; anything longer has to be found on your own machine.
  2. Create an onion address by uploading public and secret key — upload the two files mkp224o produced.
  3. Create an onion address by specifying public and secret key — paste the contents of hs_ed25519_public_key and hs_ed25519_secret_key instead of uploading files.
The Create a New Onion Address card in the portal: Option 1 asks for character(s) with a four-character limit, Option 2 uploads the public and secret key files, Option 3 takes the keys as text

This page adds an additional address (an alias) to the service and costs US$ 1.00 per month per address — the card says so above the options. To replace the service's main address instead, use the manage page described in How to change the main onion address of your onion service.

Two practical notes:

  • The secret key is the service. Paste it only into the portal, over a connection you trust, and keep your own copy of the three files — if they are lost, the address is lost with them.
  • The onion address of an alias resolves to the same site, so the prefix is cosmetic. It does not add capacity, and it does not hide the main address.

Step 6 — The key files are binary: convert them first

hs_ed25519_public_key and hs_ed25519_secret_key are raw binary — opening them in an editor shows garbage, and copying that text breaks the key. The form accepts the keys in base64 or in hex dump format, so convert them with one of these two commands (run it in the folder mkp224o created):

# hex dump — one line, nothing to wrap, works the same on Linux, macOS and WSL
xxd -p hs_ed25519_public_key
xxd -p hs_ed25519_secret_key

# or base64 — -w0 stops the 76-character line wrapping (macOS: base64 -b 0)
base64 -w0 hs_ed25519_public_key
base64 -w0 hs_ed25519_secret_key

Copy the whole output of each file, without the trailing newline, and use the same format for both fields. A base64 value for a public key starts with PT0gZWQyNTUxOXYxLXB1YmxpYzogdHlwZTAgPT0A and a hex value starts with 3d3d206564323535313976312d7075626c69633a207479706530203d3d00 — if yours starts with something else you have copied the file name or a shell error, not the key.

# quick check: a v3 key file is 72 bytes (64-byte secret: 100 bytes)
wc -c hs_ed25519_public_key hs_ed25519_secret_key

Related articles

Tags:
  • Onion Service
  • Onion Address
  • Tor

24/7 Expert Support

Our experts are always on hand to help answer your questions, get you started, and grow your presence online. You can email us any time