magic-wormhole

magic-wormhole is a secure file transfer tool that gets data from one computer to another using a short, one-time wormhole code — something like 7-crossbow-banana — rather than requiring IP addresses, port forwarding, or shared cloud accounts. Both sides run wormhole and the code is the only rendezvous needed. This is the Rust reimplementation of the original Python tool, and it extends the protocol with direct peer-to-peer connections across NATs and firewalls, removing the need to relay all data through a central server.

Features

• Short wormhole codes — human-pronounceable, one-time codes are generated automatically and copied to your clipboard for easy sharing.
• End-to-end encryption — files are encrypted using the SPAKE2 password- authenticated key exchange protocol; the relay server never sees the content.
• NAT traversal — establishes direct connections across the internet, including through firewalls, without any manual port forwarding.
• Port forwarding — forward a local port to a recipient over a wormhole connection (experimental).
• Multi-recipient transfers — send the same file to multiple people from a single wormhole (experimental).
• Fuzzy code completion — tab-complete wormhole codes in the shell.
• Clipboard integration — the generated code is automatically copied to your clipboard on supported platforms.

Installation

cargo install --locked --git https://github.com/magic-wormhole/magic-wormhole.rs

# Debian / Ubuntu
# The apt package installs the Python version. For the Rust version,
# use the cargo command above or download a binary from the releases page:
# https://github.com/magic-wormhole/magic-wormhole.rs/releases

# Fedora
# Same as above — dnf ships the Python version.
# Use cargo or a release binary for the Rust version.

# macOS
brew install magic-wormhole

# Arch Linux
pacman -S magic-wormhole.rs

# Nix
nix-env -iA nixpkgs.magic-wormhole-rs

Note: On macOS and most Linux package managers the magic-wormhole package refers to the original Python implementation. The Rust version is available as magic-wormhole.rs or magic-wormhole-rs in repositories that package it separately. The two versions are wire-compatible for basic file transfers.

Usage

Sending a file

# Send a file — prints a wormhole code and copies it to the clipboard
wormhole send photo.jpg

# Send multiple files as an archive
wormhole send report.pdf notes.txt

# Send an entire directory (packed as a tarball on the sender's side)
wormhole send --archive project/

The sender sees output like:

Wormhole code: 7-crossbow-banana
# Share this code with the recipient

Receiving a file

# Receive using the code the sender shared with you
wormhole receive 7-crossbow-banana

Both peers must be running simultaneously. Once the recipient enters the code and confirms, the encrypted transfer begins directly between the two machines.

Port forwarding

# Forward local port 8080 to the recipient's machine (experimental)
wormhole forward 8080

# On the receiving end
wormhole forward receive <code>

How it works

1. The sender connects to a publicly accessible mailbox server (wormhole.transfer.magic-wormhole.io by default) and registers a short code.
2. The recipient connects to the same mailbox server using the code.
3. Both sides perform a SPAKE2 key exchange — the short code is the shared password. This produces a strong session key without ever transmitting it.
4. If a direct connection between the two peers is possible (via NAT traversal), the actual file data flows peer-to-peer and never touches the relay.
5. If a direct connection fails, the data is relayed through a transit relay server, still end-to-end encrypted.

Rust vs Python implementation