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

> magic-wormhole sends files and text between computers using short human-readable codes like "7-crossover-clockwork". End-to-end encrypted via PAKE, relay-free when possible, and the original inspiration for croc and friends.

## Install

Save in your project root:

# magic-wormhole — File Transfer with Human-Readable Codes

## Quick Use
```bash
# Install
pip install magic-wormhole
# or
brew install magic-wormhole
sudo apt install magic-wormhole

# Sender
wormhole send report.pdf
# -> Sending 1.2 MB file named 'report.pdf'
# -> On the other computer, please run:
# -> wormhole receive 7-crossover-clockwork

# Receiver
wormhole receive 7-crossover-clockwork
```

## 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
```bash
# 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
# 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
| Feature | magic-wormhole | croc | OnionShare | Wormhole.app (web) | Snapdrop |
|---|---|---|---|---|---|
| Transport | Python (TCP) | Go (TCP) | Tor | Browser (WebRTC) | Browser (WebRTC) |
| PAKE | SPAKE2 | PAKE | Tor-auth | E2EE web | Peer-to-peer |
| Setup | pip install | Single binary | Tor Browser + app | URL only | URL only |
| File-size limit | None | None | None | 10GB (web) | None |
| Python API | Yes | No | No | No | No |
| Best For | Python tooling, research | One-off quick sends | Anonymity | Non-technical | Local network |

## 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

---
Source: https://tokrepo.com/en/workflows/06dc2ed5-3859-11f1-9bc6-00163e2b0d79
Author: AI Open Source