Magic Wormhole: Get things from one computer to another, safely

Summary

Welcome Get things from one computer to another, safely. things: are files, but can also be TCP or other network streams; one computer to another: is usually via a P2P connection, but can use a TURN-like relay depending on network conditions; safely: uses a PAKE construction to ensure high-security, end-to-end encryption with human-sized codes We realize that some of that might sound like Magic, so let’s examine each piece a little more closely. 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 Ma...