magic-wormhole — Get Things from One Computer to Another, Safely

What it is

magic-wormhole is a command-line tool that sends files and text between computers using short, human-readable wormhole codes like '7-crossover-clockwork'. It provides end-to-end encryption via the PAKE (Password-Authenticated Key Exchange) protocol, meaning neither the relay server nor any intermediary can read your data. No accounts, no configuration, no firewall rules needed.

magic-wormhole is suited for anyone who needs to transfer files between two machines quickly and securely, especially when the machines are on different networks.

How it saves time or tokens

Alternatives for file transfer include email attachments (size limits), cloud storage (requires login), scp (requires SSH setup), or USB drives (requires physical access). magic-wormhole eliminates all these requirements. The sender runs one command and gets a code. The receiver enters that code on another machine. The transfer happens directly between the two machines when possible, or through an encrypted relay when direct connection is not feasible. Total time from decision to transfer: under 30 seconds.

How to use

1. Install magic-wormhole:

pip install magic-wormhole
# or
brew install magic-wormhole
# or
sudo apt install magic-wormhole

1. On the sender machine:

wormhole send report.pdf
# Output: Wormhole code is: 7-crossover-clockwork

1. On the receiver machine:

wormhole receive 7-crossover-clockwork
# File transfers with end-to-end encryption

Example

Transferring text and directories:

# Send text
wormhole send --text 'API key: sk-abc123'
# Receiver gets the text securely

# Send an entire directory
wormhole send --zip myproject/
# Receiver gets a zip archive of the directory

# Send with a custom code for easier communication
wormhole send --code 3-purple-elephant report.pdf

The wormhole code is the only secret needed. Both sides derive the encryption key from it using SPAKE2, so the relay server never sees the key.

Related on TokRepo

• Security tools — Browse security and encryption tools
• Self-hosted tools — Explore self-hosted utilities

Common pitfalls

• Sharing the wormhole code over an insecure channel. The code is the only authentication factor. Share it verbally, via encrypted chat, or any channel you trust. Anyone with the code can receive the file.
• Expecting large file transfers to be fast over slow networks. magic-wormhole does not resume interrupted transfers in the default implementation. For very large files over unreliable connections, consider tools with resume support.
• Not realizing the code expires after one use. Each wormhole code is single-use. If the transfer fails, you need to generate a new code.