Magic Wormhole

Last reviewed Aug 26, 2026 · 779 words

wormhole send backup.tar.gz
# Wormhole code is: 7-crossover-clockwork

Read that code out over the phone, the other person types wormhole receive 7-crossover-clockwork, and the file arrives end-to-end encrypted with no account, no size limit and no server that ever sees plaintext. That is the entire product, and for the specific case of "get this one thing to that one machine, right now" nothing else in the file sync category is faster. It is a 32 MB Python process, it rates Easy because there is nothing to configure, and it has been doing the same job since 2016.

Why a three-word code is safe

The code is not a password in the usual sense. Wormhole uses a PAKE (password-authenticated key exchange, SPAKE2 specifically), so both sides derive a strong session key from the weak code, and an attacker who guesses wrong gets exactly one failed attempt before the mailbox is consumed. Two words drawn from lists of 256 each give 65,536 combinations, and only one guess is allowed, which is why the codes can stay short enough to say aloud. The words come from the PGP word list, chosen to be unambiguous when spoken, which is why you get "crossover" and "clockwork" rather than random syllables.

Where it beats LocalSend and Syncthing

Wormhole is terminal-only and both ends must be online at the same time. Those two constraints rule it out for family use and for "drop it now, pick it up tomorrow". They are exactly right for admin work: pulling a database dump off a VPS, moving an SSH key onto a fresh install, or sending a 40 GB disk image to a colleague without touching a cloud bucket.

Install without touching the system Python

pipx install magic-wormhole
wormhole send --text "the wifi password is ..."
wormhole send ./photos/        # directories are tarred on the fly

There are compatible reimplementations in Rust (wormhole-rs) and Go (wormhole-william) that ship as single binaries and speak the same protocol, so a Python-free server can still receive from the Python client. --text sends a short string instead of a file, which is the quiet killer feature for one-time codes and passwords: nothing hits a chat log, nothing hits disk.

Transfers go direct when they can, via relay when they cannot

Two servers are involved and neither can read your data. The mailbox server (relay.magic-wormhole.io by default) brokers the small encrypted handshake. The transit relay (transit.magic-wormhole.io) forwards encrypted bytes only when both sides sit behind NAT and no direct TCP path works. On a LAN, or with one side on a public IP, the transfer is direct and runs at line speed; I routinely see over 100 MB/s on gigabit. Through the public relay, expect less, because it is shared with everyone else using the default settings.

Running your own relay takes 5 minutes

The public relays are run by the project as a courtesy with no uptime promise. If wormhole is part of your toolkit, self-host both pieces on a small VPS:

pipx install magic-wormhole-mailbox-server magic-wormhole-transit-relay
twist wormhole-mailbox --port tcp:4000
twist transit-relay --port tcp:4001

Clients then pass --relay-url ws://vps.example.com:4000/v1 --transit-helper tcp:vps.example.com:4001, which belongs in a shell alias. Both servers hold nothing beyond in-flight mailboxes, need no database and idle at a few tens of MB. Put them on Tailscale if only your own machines need them, and you have removed the last third party from the path.

What I'd do

Keep wormhole installed via pipx on every machine I administer, use --text for secrets, and lean on the public relays for the occasional transfer. The moment it becomes a weekly habit, run both relay processes on the cheapest VPS I already pay for and alias the client flags. For anything with a GUI expectation, LocalSend on the LAN and Syncthing for anything ongoing; wormhole is the tool for the one-off, and it is the best one there is. The WeTransfer alternatives page covers browser-based options for recipients who will never open a terminal.