# Magic Wormhole

*November 19, 2025*
 — by Flaviu Vlaicu

> Magic Wormhole is an elegant solution to one of computing's most persistent problems: how to securely transfer files between two computers without the complexity of SSH keys, server configuration, or third-party services. Created by Brian Warner, this open-source tool embodies the principle that security and usability don't have to be mutually exclusive.



# Magic Wormhole: A Deep Dive into Secure, Simple File Transfer

## Core Architecture

### The Protocol Stack

Magic Wormhole operates on a multi-layered architecture:

**1. The Mailbox Server (Rendezvous Server)**
- A WebSocket-based relay that facilitates initial connection establishment
- Default public server: `ws://relay.magic-wormhole.io:4000/v1`
- Stores encrypted messages temporarily
- Never sees plaintext data
- Can be self-hosted for increased reliability

**2. The Transit Relay**
- Handles actual data transfer when direct peer-to-peer connections fail
- Used when both peers are behind NAT
- Default server: `tcp:transit.magic-wormhole.io:4001`
- All data passing through is end-to-end encrypted

**3. Connection Negotiation**
The tool attempts multiple connection strategies in parallel:
- Direct peer-to-peer connection (when peers are on same LAN)
- Direct connection over the internet (when one peer has public IP)
- Relayed connection via Transit Relay (as fallback)

### Cryptographic Foundation: PAKE and SPAKE2

The security heart of Magic Wormhole is **Password-Authenticated Key Exchange (PAKE)**, specifically the SPAKE2 algorithm developed by Abdalla and Pointcheval.

**How PAKE Works:**
1. Uses a short, low-entropy password (the wormhole code) to establish a strong, high-entropy shared key
2. Trades interaction for offline attack resistance
3. An attacker must perform a man-in-the-middle attack during the initial connection AND correctly guess the code
4. With default 16-bit codes, attackers have only a 1-in-65,536 chance per attempt
5. Each code is single-use only, limiting attack opportunities

**Encryption Details:**
- Session keys derived from PAKE phase
- Data encrypted using NaCl/libsodium "secretbox"
- 256-bit shared secrets after successful key exchange
- All file data encrypted end-to-end before transmission

### The Wormhole Code System

Codes follow a structured format: `[number]-[word]-[word]`
- Example: `7-guitarist-revenge` or `3-passenger-watchword`
- Nameplate (number): Identifies the specific mailbox (typically 1-2 digits)
- Words: Phonetically-distinct wordlist for clarity
- Tab-completion on receiver side minimizes typing errors
- Default 16-bit entropy, configurable with `--code-length`

## Installation and Platform Support

### Python Implementation (Original)
```bash
pip install magic-wormhole
```

**Requirements:**
- Python 3.10+ (tested up to 3.12)
- Dependencies: SPAKE2, pynacl, Twisted, autobahn
- Packaged in many OS repositories (Debian, Ubuntu, Arch, etc.)

### Alternative Implementations

**Rust Implementation:**
```bash
cargo install magic-wormhole
```
- More performant in many scenarios
- Better cross-platform binary distribution
- Available at: `magic-wormhole/magic-wormhole.rs`

**Go Implementation (wormhole-william):**
```bash
go install github.com/psanford/wormhole-william@latest
```
- Excellent performance characteristics
- Single binary distribution
- Compatible with Python implementation
- Available prebuilt binaries

**GUI Implementations:**
- **Rymdport**: Cross-platform GUI (formerly wormhole-gui)
- **GNOME Warp**: Native GNOME integration
- **iyox Wormhole**: Android client
- **Wormhole File Transfer**: QR code feature for mobile transfers

All implementations maintain protocol compatibility, allowing Python clients to communicate with Rust or Go clients seamlessly.

## Use Cases

### 1. Ad-Hoc File Transfer
The primary and most common use case—transferring files when you're already in communication:
- Phone conversations: "Let me send you that file" → generate code → speak it
- Video calls: Send code via chat while talking
- In-person: Show code on screen or speak it
- IRC/Slack: Paste code in chat for direct transfer

### 2. Password and Credential Delivery
More secure than email or messaging apps:
```bash
wormhole send --text "username:password123"
```
Perfect for:
- Delivering initial passwords to new users
- Sharing API keys or tokens
- Distributing SSH keys or certificates

### 3. Application Integration

**Tahoe-LAFS Integration:**
- Uses wormhole protocol for user invitations
- Exchanges secret connection details via secure mailbox
- No server-side password storage required

**Magic Folder:**
- Utilizes wormhole for folder sharing invitations
- Grants access to synchronized folders
- Exchanges capability strings securely

**Potential Use Cases for Developers:**
- Client provisioning without web portals
- Peer-to-peer messaging setup
- Distributed system node initialization
- Mobile app pairing (QR codes + wormhole codes)

### 4. Directory Transfer
Send entire directory structures:
```bash
wormhole send my-project/
```
Note: Original Python implementation requires zipping first; Rust and Go implementations handle directories natively.

### 5. Cross-Platform Transfers
Works seamlessly between:
- Windows ↔ Linux
- macOS ↔ Windows
- Linux ↔ Linux
- Mobile (Android) ↔ Desktop

### 6. Air-Gapped Networks (with Tor)
Enhanced privacy mode:
```bash
wormhole --tor send filename
```
- Routes traffic through Tor network
- Increases anonymity
- Useful for sensitive environments
- Supports .onion relay servers

## Key Benefits

### 1. Zero Configuration
- No SSH keys to generate or exchange
- No port forwarding required
- No firewall configuration needed
- No user accounts or registration
- No shared passwords to maintain

### 2. Strong Security
- End-to-end encryption
- Forward secrecy (codes are single-use)
- Resistant to offline attacks
- Minimal trust required in relay servers
- Open-source and auditable

### 3. Human-Friendly
- Short, pronounceable codes
- Tab completion reduces typing
- Clear error messages
- Works across NAT boundaries
- Automatic relay fallback

### 4. Lightweight
- Small download size
- Minimal dependencies (especially Go/Rust versions)
- Low resource consumption
- Works on Raspberry Pi and similar devices

### 5. Cross-Platform
- Available for all major operating systems
- Protocol compatibility between implementations
- Mobile support (Android)
- Can be embedded in other applications

### 6. Privacy-Preserving
- No permanent account creation
- No tracking or analytics
- Can be used with Tor
- Self-hostable infrastructure

## Performance Benchmarks

Performance varies significantly based on implementation, network conditions, and hardware:

### Observed Transfer Speeds

**Python Implementation:**
- LAN transfers: 11.6 MB/s (reported in issue #276)
- Internet via public relay: 40-50 MB/s typical
- Custom relay: 50-70 MB/s achievable
- Small file example: 3.75 MB transferred at 1.81 MB/s

**Rust Implementation:**
- Performance issues noted on M1 Mac (bottleneck under investigation)
- Other platforms: comparable to Python or better
- Generally more CPU-efficient than Python

**Go Implementation (wormhole-william):**
- Full gigabit speeds achievable on good networks
- Excellent CPU efficiency
- Consistent performance across platforms

### Bottlenecks and Limitations

**Common Issues:**
1. **Public Relay Congestion**: The free public relay can become saturated
2. **NAT Traversal Overhead**: Relay routing slower than direct P2P
3. **Single-threaded Transfers**: No parallel stream support
4. **CPU Encryption Overhead**: On low-power devices (Raspberry Pi ~7s startup)
5. **Windows Performance**: Python version historically slower on Windows

**Comparison with Other Tools:**
- SSH/SCP: ~40 MB/s (single-threaded limitation)
- Magic Wormhole (public relay): 40-50 MB/s
- Magic Wormhole (private relay): 50-100+ MB/s
- Direct iperf: 750+ MB/s (baseline network capability)

### Performance Optimization Strategies

1. **Run Your Own Relay:**
```bash
pip3 install magic-wormhole-transit-relay
twistd3 transitrelay
```
Then use:
```bash
wormhole send --transit-helper=tcp:YOUR_IP:4001 filename
```

2. **Use Go or Rust Implementations:**
- Lower overhead
- Better multi-platform performance
- Faster startup times

3. **Optimize Network Path:**
- Same LAN: Direct P2P (fastest)
- Different networks with one public IP: Still direct
- Both behind NAT: Requires relay (slower)

4. **Hardware Considerations:**
- Raspberry Pi: Expect ~19s startup (Python), ~7s with optimizations
- Modern x86/ARM: Minimal CPU overhead
- Network bandwidth usually the limiting factor

## Advanced Features

### Custom Code Generation
```bash
wormhole send --code-length=4 file.txt  # 4-word code (more entropy)
```

### Text Snippets
```bash
echo "secret message" | wormhole send --text
```

### Appid (Application Identifier)
Different appids create separate namespaces:
```bash
wormhole --appid=custom.app send file
```
Useful for:
- Application-specific transfers
- Isolated communication channels
- Custom protocol implementations

### Offline Codes
Both sides can prepare codes offline, then connect later when online.

### Verifier Codes
Additional verification for paranoid users:
- Compare verifier strings out-of-band
- Confirms no MITM attack occurred
- Optional but recommended for sensitive transfers

### API Integration
```python
from wormhole import wormhole

w = wormhole.create(appid, relay_url, reactor)
code = yield w.get_code()
# Display code to user
yield w.send(data)
```

## Comparison with Alternatives

### vs. Croc
**Croc** (written in Go) is inspired by Magic Wormhole but uses a different protocol:

**Advantages of Croc:**
- Resume support for interrupted transfers
- IPv6 support
- Multiple file transfers
- Folder sending without zipping
- Can set custom code phrases
- Self-relay support built-in

**Disadvantages of Croc:**
- Not compatible with Magic Wormhole protocol
- Known security concerns (fixed but historical)
- Fragments the user base
- Different cryptographic approach (not SPAKE2)

**Verdict:** Croc offers more features but Magic Wormhole has better-vetted security and wider protocol support.

### vs. SCP/SFTP
**Magic Wormhole advantages:**
- No SSH key setup
- Works across NAT
- No hostname/IP needed
- User-friendly codes

**SCP/SFTP advantages:**
- Established, trusted protocol
- Better performance (when configured)
- Scriptable with known infrastructure
- Standard on Unix systems

### vs. Dropbox/Google Drive
**Magic Wormhole advantages:**
- No account required
- Direct peer-to-peer (when possible)
- End-to-end encrypted
- No file size limits (server-dependent)
- Ephemeral (no cloud storage)

**Cloud services advantages:**
- Persistent storage
- Multiple recipients
- Web interface
- Sync capabilities
- Mobile apps

### vs. WebRTC (ShareDrop, FilePizza)
**Magic Wormhole advantages:**
- Command-line interface
- Scriptable
- Library for integration
- Works without browser

**WebRTC advantages:**
- No installation needed
- Visual interface
- QR code support
- Mobile-friendly

## Security Considerations

### Trust Model

**What you must trust:**
1. The cryptographic implementation (SPAKE2, NaCl)
2. Your communication channel for the code (phone, in-person, etc.)
3. The software implementation itself

**What you don't need to trust:**
1. The Mailbox server (sees only encrypted data)
2. The Transit relay (also sees only encrypted data)
3. Network infrastructure (encryption protects in-transit)

### Attack Scenarios

**Man-in-the-Middle:**
- Attacker must be active during initial connection
- Must correctly guess code in single attempt (1/65,536 chance)
- Failed attempts generate error messages
- Multiple failed attempts very noticeable

**Eavesdropping:**
- All data encrypted with strong keys
- Even if relay is compromised, data remains secure
- Forward secrecy: past sessions can't be decrypted

**Code Interception:**
- If attacker learns code and acts immediately, attack possible
- Mitigation: Use secure channels for code transmission
- Use verifier codes for high-security scenarios
- Codes expire after use or timeout (~3 minutes in older versions)

### Known Vulnerabilities

As noted by Jeff Geerling: "There are Known Vulnerabilities, so I wouldn't think about sending over state secrets."

**Recommendations:**
- Don't use for classified information
- Verify verifier codes for sensitive transfers
- Use Tor mode for anonymity requirements
- Self-host relays for corporate use
- Keep software updated

## Developer Information

### Library API

**Twisted (Asynchronous):**
```python
from twisted.internet import reactor
from wormhole import wormhole

def send_file(filename):
    w = wormhole.create(appid, relay_url, reactor)
    code = yield w.get_code()
    print(f"Code: {code}")
    yield w.send(open(filename, 'rb').read())
    yield w.close()
```

**Future Blocking API:**
The project plans to add synchronous/blocking support for easier integration.

### Running Your Own Infrastructure

**Mailbox Server:**
```bash
pip install magic-wormhole-mailbox-server
wormhole-mailbox-server --port=4000
```

**Transit Relay:**
```bash
pip install magic-wormhole-transit-relay
twistd3 transitrelay --port=4001
```

**Docker Support:**
Both can be easily containerized for deployment.

### Protocol Extensions

The core protocol is extensible:
- **Dilation**: Future feature for long-lived channels
- **Custom Application Protocols**: Build on wormhole foundation
- **Multi-message Support**: Send multiple messages over one wormhole

## The Ecosystem

### Official Projects
- `magic-wormhole` - Original Python implementation
- `magic-wormhole.rs` - Rust implementation
- `magic-wormhole-mailbox-server` - Server component
- `magic-wormhole-transit-relay` - Relay component

### Community Projects
- `wormhole-william` - Go implementation (psanford)
- `Rymdport` - Cross-platform GUI
- `GNOME Warp` - GNOME desktop integration
- `croc` - Inspired alternative with different protocol
- Various mobile apps and web interfaces

### Package Availability
Magic Wormhole is available in:
- Debian/Ubuntu repositories
- Arch Linux (AUR)
- Fedora/RHEL repositories
- Homebrew (macOS)
- Chocolatey (Windows)
- Snap Store
- Flathub

## Real-World Adoption

Magic Wormhole has been adopted by various projects and organizations:

**Academic Use:**
- Featured in cryptography courses
- Used for secure research data exchange
- Example of practical PAKE implementation

**Corporate Use:**
- IT departments for secure credential distribution
- DevOps teams for quick file sharing
- Remote support scenarios

**Open Source Community:**
- Integrated into Tahoe-LAFS distributed storage
- Used by Magic Folder for secure sharing
- Referenced in security best practices

**Uniswap Assessment:**
While not directly related to Magic Wormhole, the document mentions other secure transfer protocols. The Wormhole blockchain bridge (different project) was rated #1 by Uniswap's Bridge Assessment Committee—showing the "wormhole" concept has broad appeal in secure communication.

## Future Directions

### Planned Improvements

**Dilation:**
- Long-lived wormhole connections
- Replace separate Transit class
- Multiple bi-directional streams
- Better for interactive applications

**Enhanced NAT Traversal:**
- Improved hole-punching techniques
- STUN/TURN integration
- Better direct connection success rates

**Performance Optimization:**
- Multi-threaded transfers
- Parallel stream support
- Better buffering strategies
- Reduced protocol overhead

**Mobile Experience:**
- Native iOS apps
- Improved Android support
- QR code integration
- Camera-based code scanning

### Community Wishlist
- Resume support (being worked on)
- Better directory handling (solved in Rust/Go)
- GUI improvements
- WebAssembly support
- Browser plugin
- Integration with more platforms

## Conclusion

Magic Wormhole represents a rare achievement in security software: it makes the secure option also the easiest option. By leveraging PAKE cryptography and a clever relay architecture, it eliminates the friction that typically accompanies secure file transfer.

**Key Takeaways:**
- Simple UX: Just two commands and a short code
- Strong security: End-to-end encryption with forward secrecy
- Zero setup: No configuration, keys, or accounts
- Cross-platform: Works everywhere, interoperably
- Open source: Auditable and trustworthy
- Extensible: Library for custom applications

**When to Use Magic Wormhole:**
- Ad-hoc file transfers during calls/chats
- Secure credential delivery
- Quick file sharing without cloud services
- Cross-platform transfers
- NAT-traversal scenarios
- Application key exchange

**When Not to Use:**
- Classified/highly sensitive data (use verified secure channels)
- Large-scale file distribution (use proper CDN)
- Persistent file sharing (use cloud storage)
- Resumable transfers of huge files (consider croc or BitTorrent)

For most everyday file transfer needs, Magic Wormhole hits the sweet spot of security, simplicity, and practicality. It's a tool that deserves a place in every developer's and power user's toolkit.

## Resources

- **Official Documentation:** https://magic-wormhole.readthedocs.io
- **GitHub (Python):** https://github.com/magic-wormhole/magic-wormhole
- **GitHub (Rust):** https://github.com/magic-wormhole/magic-wormhole.rs
- **Go Implementation:** https://github.com/psanford/wormhole-william
- **PyCon 2016 Talk:** https://us.pycon.org/2016/schedule/presentation/1838/
- **Mailbox Server:** https://github.com/magic-wormhole/magic-wormhole-mailbox-server
- **Transit Relay:** https://github.com/magic-wormhole/magic-wormhole-transit-relay

## Acknowledgments

Created by Brian Warner, with contributions from the open-source community. The project demonstrates the power of good cryptographic engineering combined with thoughtful UX design.

---

*Last Updated: November 2024*  
*Based on Magic Wormhole 0.21.x and ecosystem projects as of 2024*


---
*Source: [https://vlaicu.io/posts/wormhole/](https://vlaicu.io/posts/wormhole/)*