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

Introduction

magic-wormhole was created by Brian Warner (Tahoe-LAFS, LeastAuthority) and is the academic "original" behind the wave of short-code file-sharing tools (including croc). Its PAKE-based code-phrase design is what later tools adopted. wormhole itself is Python-native and plays well with scripts and automation.

With over 22,000 GitHub stars, magic-wormhole remains a favorite in research and Python-heavy environments. The codebase is meticulously tested and the cryptography has been peer-reviewed.

What magic-wormhole Does

wormhole has two sides: sender and receiver. Each contacts the "mailbox" server with a one-time code-phrase. After both sides arrive, they run PAKE (SPAKE2) to derive a shared secret without the server seeing anything but ciphertext metadata. They then open a direct transport channel (relay-free if NAT lets them; relayed otherwise) and transfer data encrypted end-to-end.

Architecture Overview

Sender                     Mailbox                    Receiver
   |                          |                           |
   |-- connect + "code" ----->|                           |
   |                          |<----- connect + "code" ---|
   |                       [match]                        |
   |<--- SPAKE2 exchange -----|----- SPAKE2 exchange ---->|
   |                       [derive key]                   |
   |                          |                           |
   |=== direct / relayed encrypted channel for data ==    |

Key crypto:
   SPAKE2 (balanced PAKE) for key derivation
   NaCl SecretBox (Salsa20 + Poly1305) for data
   One-time codes, immediate expiration

Self-Hosting & Configuration

# Send a directory
wormhole send ./project

# Send text-only (no file — just a clipboard-like snippet)
wormhole send --text "short text to share"
wormhole receive <code>

# Self-host a mailbox server
pip install magic-wormhole-mailbox-server
twist mailbox start --port=4000

# Self-host a transit relay (for traffic that can't go direct)
pip install magic-wormhole-transit-relay
twist transit start --port=4001

# Point clients at your servers
wormhole send --relay-url ws://yourserver.com:4000/v1 \
              --transit-helper tcp:yourserver.com:4001 \
              myfile

# Python API — embed in your own tooling
import twisted.internet.defer
from wormhole import create

@twisted.internet.defer.inlineCallbacks
def demo(reactor):
    w = create("myapp", "ws://relay.magic-wormhole.io:4000/v1", reactor)
    code = yield w.get_code()
    print("code:", code)
    yield w.send_message(b"hello from Python")

Key Features

• PAKE-based — short codes provide strong security
• Relay-free when possible — direct P2P via hole-punching
• Cross-platform — Python wheel works on macOS, Linux, Windows
• Scriptable — Python API for custom tools
• Self-hostable — run your own mailbox and transit relay
• Tahoe-LAFS integration — ideal for peer-to-peer backups
• Security-focused — audited crypto, minimal attack surface
• Text + file + directory — sends anything

Comparison with Similar Tools

FAQ

Q: wormhole vs croc? A: Same idea, different languages. wormhole is Python (good for scripts, Tahoe-LAFS integration). croc is Go (single-binary, slightly faster on large files). For interactive use, either works; for automation, pick whichever language you prefer.

Q: Is it really secure with short codes? A: Yes. The code contains a numerical prefix that identifies the session; SPAKE2 is a balanced PAKE resistant to offline dictionary attacks. An attacker would need real-time online access when the transfer is happening.

Q: What's the max file size? A: No hard limit. It's used to transfer multi-GB datasets routinely.

Q: Can I run behind a corporate firewall? A: Usually yes — the WebSocket relay uses port 4000 (or whatever you configure). If blocked, self-host a relay on an allowed port and supply --relay-url.

Sources

• GitHub: https://github.com/magic-wormhole/magic-wormhole
• Author: Brian Warner
• License: MIT