Quick start · Usage · Why VanityRig · Comparison · Contributing · Security

---

Find a Tor v3 .onion address containing your word — at the start, the end, or anywhere — and know exactly how long it will take before you spend any CPU on it.

curl -fsSL https://raw.githubusercontent.com/bytestrix/vanityrig/main/install.sh | bash
vanityrig

---

Quick start

1. Install (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/bytestrix/vanityrig/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/bytestrix/vanityrig/main/install.ps1 | iex

2. Run it

vanityrig

No flags to learn. Type a word, press s, and watch it search.

Key	Action
tab / ↑↓	move between fields
←→	change a selection
enter	edit a field
s	start / stop the search
v	cycle the log level filter
q	quit

Already know what you want? vanityrig <word> [flags] — see Usage.

Found an address? See Using your address with Tor.

Other ways to install

Homebrew (macOS/Linux):

brew install --cask bytestrix/tap/vanityrig

Debian/Ubuntu (.deb) or Fedora/RHEL (.rpm): download the package for your architecture from the latest release and install it:

sudo dpkg -i vanityrig_*_linux_amd64.deb      # Debian/Ubuntu
sudo rpm -i vanityrig_*_linux_amd64.rpm       # Fedora/RHEL

Go toolchain already installed:

go install github.com/bytestrix/vanityrig/cmd/vanityrig@latest

Docker:

docker build -t vanityrig https://github.com/bytestrix/vanityrig.git
docker run --rm -it -v "$PWD/keys:/keys" vanityrig cafe -out /keys

Build from source:

git clone https://github.com/bytestrix/vanityrig.git
cd vanityrig
make build
make test

Optional, for any install method: put mkp224o on your PATH. VanityRig uses it automatically for prefix searches — it's roughly 8x faster per core than VanityRig's own engine for that mode (measured, not estimated — see internal/engine/bench_test.go). Suffix and anywhere searches always run on VanityRig's built-in engine.

---

Usage

vanityrig                          # guided prompts (see Quick start above)
vanityrig <word> [word...] [flags] # the same thing, one command — for scripts and repeat use

If you don't say where the word should go, it compares prefix, suffix, and anywhere, and asks:

vanityrig vanityrig                          # compares all 3 modes, asks which to run
vanityrig vanityrig -match anywhere          # skip the question, go straight to anywhere mode
vanityrig vanityrig ritrigvan -stop-after 3  # OR search, stop after 3 total matches
vanityrig vanityrig -check                   # just the numbers, don't offer to run anything
vanityrig vanityrig -y                       # skip every prompt, use the recommended mode
vanityrig -benchmark -threads 8              # measure real keys/sec on this machine, no search

Flag	Default	Meaning
-match	(ask)	prefix, suffix, or anywhere — skips the question if set
-out	~/.vanityrig/keys	where found keys are saved
-threads	all cores	CPU threads to use
-stop-after	0 (never)	stop once this many matches are found
-rate	22.2M	assumed combined keys/sec, used for the estimate
-budget	24h	longest search you'd accept, for alternatives
-check	off	show the estimate and exit — don't offer to search
-y	off	skip every prompt and start immediately
-plain	off	plain log lines instead of the live dashboard
-benchmark	off	measure real keys/sec on this machine and exit — no search, no files written
-benchmark-time	5s	how long -benchmark measures for

Press q to quit, or s to stop a running search without quitting — the dashboard stays up with the final logs and stats, and s again re-arms it to search again (progress is saved continuously, so restarting the same word continues from where it left off instead of starting over). A match is written to disk before it's announced, so a crash between finding and saving can't lose it; a plaintext and CSV summary of every match (address, timestamp, save directory) is also appended to matches.txt/matches.csv in the output directory, alongside — never instead of — the real key files, which must stay in Tor's exact binary format to be usable.

Exit codes: 0 achievable (however long the odds), 1 unsatisfiable (well formed, but no matching address exists in any mode), 2 malformed input.

---

Why VanityRig

• Matches anywhere in the address, not just the start. A word has up to 47 possible positions in a 56-character address — matching any of them is often 10-50x faster than pinning it to the front.
• Compares where the word can go, not just how long it takes. Prefix, suffix, and anywhere have very different costs for the same word, so VanityRig checks all three and tells you which is achievable — instead of silently assuming prefix, or offering to shorten your word to make it faster.
• Catches impossible searches before you waste time on them. The last two characters of every v3 address are constrained by the protocol — some words can never appear at the end. VanityRig names the exact rule and offers a fix (search all four legal endings together) instead of searching forever for something that can't exist.
• Shows its work. Every estimate is a real, checkable calculation — exponent form, exact count, assumed rate — so a wrong number is visible on its face rather than hidden behind a verdict.
• Has its own search engine, so suffix and anywhere-position matching actually run instead of being advertised and silently unsupported. Keys are byte-identical to mkp224o's output, verified in the test suite. It batches the expensive part of key generation (a modular field inversion) across many candidates at once instead of paying it per key, which is roughly 11x faster than the straightforward version of the same engine — measured, not estimated.

---

Comparison

	VanityRig	mkp224o
Prefix match	✅ (uses mkp224o if installed)	✅
Suffix match	✅	❌
Match anywhere	✅	only via a custom --enable-regex build
Time estimate before searching	✅	❌
Detects impossible patterns	✅	❌
Live dashboard	✅	❌
Resume after stop	✅	❌
Prefix speed per core	~8x slower (built-in engine)	fastest
GPU	not yet (#2)	❌

VanityRig isn't trying to replace mkp224o — it drives it for prefix searches when it's on your PATH, and fills in what it doesn't do.

---

Contributing

Contributions welcome. See CONTRIBUTING.md and the Code of Conduct. Open an issue before a large PR. make test and make lint must pass.

New here? Start with good first issue.

Found a security issue rather than an ordinary bug? Please don't open a public issue — see SECURITY.md.

License

MIT — permissive and simple: use it, modify it, ship it in something closed-source if you want, just keep the copyright notice.

Contributors