wormhole

Send a file

$ wormhole send [path/to/file]

$ wormhole receive [wormhole_code]

$ wormhole send

$ wormhole send --code [custom_code] [path/to/file]

wormhole [GLOBAL_OPTIONS] [SUBCOMMAND_OPTIONS] [ARGUMENTS]

Common Subcommands:
wormhole send [OPTIONS] FILE_OR_DIRECTORY
wormhole send [OPTIONS] --text TEXT_TO_SEND
wormhole receive [OPTIONS] [CODE]

Global Options:
    Options applicable to the wormhole command itself.

--version
    Show program's version number and exit.

--help, -h
    Show a help message and exit.

--code-length
    Use a code of length N words (default: 2).

--transit-helper
    Override the default transit relay server URL.

--rendezvous-url
    Override the default rendezvous server URL.

--allocate-relay
    Allocate a public relay for potentially faster and more reliable connections (when direct connection fails).

--hide-progress
    Suppress the progress bar during file transfers.

Send Subcommand Options:
    Options specific to the wormhole send subcommand.

--text, -t
    Send a text message instead of a file or directory.

--verify
    Ask the receiver to verify a checksum of the transferred data.

Receive Subcommand Options:
    Options specific to the wormhole receive subcommand.

--accept-file
    Automatically accept the transfer without prompting (use with caution, unsafe if sender is unknown).

--output-file , -o
    Write received data to the specified filename instead of the default.

magic-wormhole is a command-line tool that allows you to securely and simply transfer files, directories, or short pieces of text between computers. It uses a PAKE (Password-Authenticated Key Exchange) protocol to establish a secure, end-to-end encrypted channel using a short, human-speakable code.

The process involves one party sending an item and getting a unique 'wormhole code', which they then verbally or securely share with the receiving party. The receiving party enters this code to initiate the transfer. This method avoids the need for complex network configurations, IP addresses, or pre-shared keys, making it highly user-friendly and robust against many common network attacks. Data is encrypted in transit and never stored on intermediary servers.

Requires both sender and receiver to be online simultaneously for the initial connection handshake. The system relies on a public 'rendezvous server' for initial key exchange; while the server never sees the plaintext data or shared secrets, its availability and integrity are crucial for the connection setup. Self-hosting a server is an option for increased control. It is not a continuous tunnel or VPN; it's designed for one-off file/text transfers. The security fundamentally relies on the out-of-band sharing of the wormhole code. If the code is intercepted or guessed, the security is compromised.

magic-wormhole uses SPAKE2+, a Password-Authenticated Key Exchange protocol. This allows two parties to agree on a strong cryptographic key based on a low-entropy password (the wormhole code) without revealing the password itself, even to an eavesdropper or the rendezvous server. This ensures that only someone with the correct code can join the secure channel.

The 'rendezvous server' is used only for the initial handshake and exchange of encrypted PAKE messages, helping the two peers find each other. Once the secure channel is established, data often flows directly peer-to-peer. If a direct connection isn't possible (e.g., due to NAT/firewall), a 'transit relay' is used to tunnel the encrypted data. Neither the rendezvous server nor the transit relay ever see the unencrypted file contents.

magic-wormhole was created by Brian Warner and first released around 2016. Its primary goal was to provide a secure, simple, and reliable method for transferring data between arbitrary computers, bypassing common complexities like firewalls and NATs, and without requiring pre-configuration or trusting intermediate servers with data. It leverages the SPAKE2+ PAKE (Password Authenticated Key Exchange) protocol, which allows two parties to derive a shared secret key over an insecure channel, given they both know a short, low-entropy password (the wormhole code). This design makes it particularly suitable for verbal code exchange.

scp(1), rsync(1), ssh(1), netcat(1)