Welcome — Magic-Wormhole 0.21.1+21.g28db005 documentation

Get Things¶

Traditionally transferring files is hard, even in 2025. The first and most popular “Thing” is a file or directory. For more on this, see the File-Transfer Protocol

Magic Wormhole can send any sort of message, though, including messages making up streams – for example, Fowl does exactly this. fowl is built on a feature called “Dilation”; see The Dilation Protocol for more detail.

From One Computer to Another¶

Magic Wormhole has several methods to connect peers. A peer uses network “hints” to suggest these ways to the other peer. This allows considerable flexibility and can succeed in many different network conditions.

Initial and relatively small messages are sent via the “Mailbox” server. This lets the two peers contact a well-known resource, and send the initial PAKE messages. After establishing this shared key, the peers bootstrap via further messages over the Mailbox. See Client-to-Client Protocol for more details.

For file-transfer, Mailbox messages contain the above-mentioned “hints” to establish a peer-to-peer connection.

If the peers are on the same LAN, they will communicate directly over the local network. When one peer has a routable, public IP address they will also communicate directly. In case both peers are behind a NAT (or otherwise can only make outbound connections) the “Transit Relay” server is used to relay messages (which are all encrypted) between the peers.

Regardless, in the end a connection is established to pass end-to-end encrypted messages between two peers (and only two peers).

Safely¶

Magic Wormhole exists (at least partly) so more software can use a cryptographic construct called “Password Authenticated Key Exchange” (PAKE), currently using the SPAKE2 variant.

This construct allows for human-sized codes to be used while still maintaining high security. Each code is one-time use only, so attackers (e.g. a malicious Mailbox server) get only a single guess when attempting to subvert a connection.

If such a guess is successful, one of the two intended peers will notice: their connection will fail, typically with a “crowded” or “scary” error.

Early in the protocol a shared secret is established, after which all peer-to-peer traffic is encrypted with keys derived directly from the shared PAKE secret. The section Known Vulnerabilities has more details about failure modes.

Example¶

Sender:

% wormhole send README.md
Sending 7924 byte file named 'README.md'
On the other computer, please run: wormhole receive
Wormhole code is: 7-crossover-clockwork

Sending (<-10.0.1.43:58988)..
100%|=========================| 7.92K/7.92K [00:00<00:00, 6.02MB/s]
File sent.. waiting for confirmation
Confirmation received. Transfer complete.

Receiver:

% wormhole receive
Enter receive wormhole code: 7-crossover-clockwork
Receiving file (7924 bytes) into: README.md
ok? (y/n): y
Receiving (->tcp:10.0.1.43:58986)..
100%|===========================| 7.92K/7.92K [00:00<00:00, 120KB/s]
Received file written to README.md

Installation¶

The easiest way to install magic-wormhole is to use a packaged version from your operating system. If there is none, or you want to participate in development, you can install from source.

$ sudo apt install magic-wormhole

$ sudo dnf install magic-wormhole

$ sudo zypper install python-magic-wormhole

$ sudo snap install wormhole

$ choco install magic-wormhole

pip install --user magic-wormhole

virtualenv venv
source venv/bin/activate
pip install magic-wormhole

Motivation¶

• Moving a file to a friend’s machine, when the humans can speak to each other (directly) but the computers cannot

• Delivering a properly-random password to a new user via the phone

• Supplying an SSH public key for future login use

Copying files onto a USB stick requires physical proximity, and is uncomfortable for transferring long-term secrets because flash memory is hard to erase. Copying files with ssh/scp is fine, but requires previous arrangements and an account on the target machine, and how do you bootstrap the account? Copying files through email first requires transcribing an email address in the opposite direction, and is even worse for secrets, because email is unencrypted. Copying files through encrypted email requires bootstrapping a GPG key as well as an email address. Copying files through Dropbox is not secure against the Dropbox server and results in a large URL that must be transcribed. Using a URL shortener adds an extra step, reveals the full URL to the shortening service, and leaves a short URL that can be guessed by outsiders.

Many common use cases start with a human-mediated communication channel, such as IRC, IM, email, a phone call, or a face-to-face conversation. Some of these are basically secret, or are “secret enough” to last until the code is delivered and used. If this does not feel strong enough, users can turn on additional verification that doesn’t depend upon the secrecy of the channel.

The notion of a “magic wormhole” comes from the image of two distant wizards speaking the same enchanted phrase at the same time, and causing a mystical connection to pop into existence between them. The wizards then throw books into the wormhole and they fall out the other side. Transferring files securely should be that easy.

Design¶

The wormhole tool uses PAKE “Password-Authenticated Key Exchange”, a family of cryptographic algorithms that uses a short low-entropy password to establish a strong high-entropy shared key. This key can then be used to encrypt data. wormhole uses the SPAKE2 algorithm, due to Abdalla and Pointcheval1.

PAKE effectively trades off interaction against offline attacks. The only way for a network attacker to learn the shared key is to perform a man-in-the-middle attack during the initial connection attempt, and to correctly guess the code being used by both sides. Their chance of doing this is inversely proportional to the entropy of the wormhole code. The default is to use a 16-bit code (use –code-length= to change this), so for each use of the tool, an attacker gets a 1-in-65536 chance of success. As such, users can expect to see many error messages before the attacker has a reasonable chance of success.

Timing¶

The program does not have any built-in timeouts, however it is expected that both clients will be run within an hour or so of each other. This makes the tool most useful for people who are having a real-time conversation already, and want to graduate to a secure connection. Both clients must be left running until the transfer has finished.

Relays¶

There are two servers involved, one of which you may never use. - the “Mailbox Server”; - and a “Transit Relay”

The wormhole library requires a “Mailbox Server” (also known as the “Rendezvous Server”): a simple WebSocket-based relay that delivers messages from one client to another. This allows the wormhole codes to omit IP addresses and port numbers. The URL of a public server is baked into the library for use as a default, and will be freely available until volume or abuse makes it infeasible to support. Applications which desire more reliability can easily run their own relay and configure their clients to use it instead. Code for the Mailbox Server is in a separate package named magic-wormhole-mailbox-server and has documentation here. Both clients must use the same mailbox server. The default can be overridden with the --relay-url option.

The file-transfer commands also use a “Transit Relay”, which is another simple server that glues together two inbound TCP connections and transfers data on each to the other (the moral equivalent of a TURN server). The wormhole send file mode shares the IP addresses of each client with the other (inside the encrypted message), and both clients first attempt to connect directly. If this fails, they fall back to using the transit relay. As before, the host/port of a public server is baked into the library, and should be sufficient to handle moderate traffic. Code for the Transit Relay is provided a separate package named magic-wormhole-transit-relay with instructions here. The clients exchange transit relay information during connection negotiation, so they can be configured to use different ones without problems. Use the --transit-helper option to override the default.

The protocol includes provisions to deliver notices and error messages to clients: if either relay must be shut down, these channels will be used to provide information about alternatives.

CLI tool¶

• wormhole send [args] --text TEXT

• wormhole send [args] FILENAME

• wormhole send [args] DIRNAME

• wormhole receive [args]

Both commands accept additional arguments to influence their behavior:

• --code-length WORDS: use more or fewer than 2 words for the code

• --verify : print (and ask user to compare) extra verification string

For more details, see Using the CLI

Library¶

The wormhole module makes it possible for other applications to use these code-protected channels. This includes Twisted support, and (in the future) will include blocking/synchronous support too. See the API docs for details.

The file-transfer tools use a second module named wormhole.transit, which provides an encrypted record-pipe. It knows how to use the Transit Relay as well as direct connections, and attempts them all in parallel. TransitSender and TransitReceiver are distinct, although once the connection is established, data can flow in either direction. All data is encrypted (using nacl/libsodium “secretbox”) using a key derived from the PAKE phase. See src/wormhole/cli/cmd_send.py for examples.

Development¶

• Bugs and patches at the GitHub project page.

• Chat via IRC: #magic-wormhole on irc.libera.chat

• Chat via Matrix: #magic-wormhole on matrix.org

To set up Magic Wormhole for development, you will first need to install virtualenv.

Once you’ve done that, git clone the repo, cd into the root of the repository, and run:

virtualenv venv
source venv/bin/activate
pip install --upgrade pip setuptools

Now your virtualenv has been activated. You’ll want to re-run source venv/bin/activate for every new terminal session you open.

To install Magic Wormhole and its development dependencies into your virtualenv, run:

If you are using zsh, such as on macOS Catalina or later, you will have to run pip install -e .'[dev]' instead.

While the virtualenv is active, running wormhole will get you the development version.

trial wormhole.test.test_cli.PregeneratedCode.test_file_tor

pkg_resources.DistributionNotFound: The 'magic-wormhole==0.9.1-268.g66e0d86.dirty' distribution was not found and is required by the application

License, Compatibility¶

This library is released under the MIT license, see LICENSE for details.

This library is compatible with Python 3.10, 3.11, 3.12, 3.13.