Magic Wormhole Encrypted File Transfer How To Send Files

Magic Wormhole provides a secure, terminal-based method for transferring files between machines without establishing a direct network connection. The tool uses end-to-end encryption with a simple wormhole metaphor: you create a code on one machine, share it with the recipient, and files flow through an encrypted channel. This approach eliminates the need for cloud storage, FTP servers, or expose-your-IP file sharing methods.

How Magic Wormhole Works

Magic Wormhole implements the SPAKE2 algorithm to establish an encrypted channel between two parties. When you initiate a transfer, the tool generates a short, human-readable code (such as 7-abc-def). The recipient enters this code on their end, and the Wormhole protocol handles key exchange, encryption, and file transfer automatically.

The encryption ensures that only the intended recipient can decrypt the files. Even if someone intercepts the wormhole code, they cannot access the transferred data without also having access to the receiving machine.

Installation

Magic Wormhole requires Python 3.7 or later. Install it using pip:

pip install magic-wormhole

On macOS, Homebrew provides a packaged version:

brew install magic-wormhole

Verify the installation by checking the version:

wormhole --version

Sending Files

The basic syntax for sending a file involves the wormhole send command followed by the file path:

wormhole send /path/to/file.txt

When executed, the command outputs a wormhole code:

Sending 1 file (1.2KB):
Wormhole code is: 7-abc-def
On the other computer, please run: wormhole receive 7-abc-def

Share this code with the recipient through a separate channel (ideally not the same network or method you’re using for the transfer).

Receiving Files

On the receiving end, the recipient runs:

wormhole receive

The command prompts for the wormhole code:

Enter receive wormhole code: 7-abc-def
Receiving 1 file (1.2KB) into: file.txt
Received file written to: file.txt

The file transfers automatically once both parties have entered the correct code.

Transferring Directories

Magic Wormhole handles directories by packaging them into a tar archive automatically. Send a directory with the same command used for files:

wormhole send /path/to/project-folder/

The receiving party receives the contents as a folder with the same name.

Text Transfer

For quick text snippets, use the --text flag to transfer content without creating a file:

wormhole send --text "Here's your API key: sk_live_xxxxx"

The recipient receives the text directly in their terminal output, useful for sharing passwords, API keys, or configuration values securely.

Advanced Usage Patterns

Specifying a Filename

Force a specific filename on the receiver’s end:

wormhole send --rename custom-name.zip /path/to/archive.zip

Transferring Multiple Files

Send multiple files in a single transfer:

wormhole send file1.txt file2.txt config.json

The recipient receives all files in a single package.

Using with Pipes

Pipe content directly into the wormhole:

cat large-log-file.log | wormhole send

This streams the content without creating an intermediate file on disk.

Verbose Mode

Enable detailed output for debugging:

wormhole send --verbose /path/to/file

This shows the encryption handshake, transfer progress, and connection details.

Security Considerations

Magic Wormhole provides several security guarantees:

End-to-end encryption: All data transfers use the SPAKE2 key agreement protocol with Curve25519 elliptic curve cryptography. The server mediating the wormhole never sees the encryption keys or file contents.

One-time codes: Each wormhole code expires after the transfer completes. A new code generates for every transfer attempt.

No authentication required: The security model relies on the code being shared through a separate channel. If an attacker guesses the code before the legitimate recipient, they could intercept the transfer.

For highly sensitive transfers, consider:

Using a code relay channel different from your primary communication method
Verifying the file hash after transfer
Transferring in a private network when possible

Common Troubleshooting

Connection timeouts: The default timeout is 90 seconds. Increase it with --timeout:

wormhole receive --timeout 300

Large file transfers: Magic Wormhole works well for files up to a few gigabytes. For larger transfers, consider splitting the archive or using alternative tools designed for massive data transfer.

Firewall issues: Both machines need outbound HTTPS access (port 443) to connect to the wormhole relay server. Corporate firewalls may block this connection.

Python version errors: Ensure you’re using Python 3.7 or later. Check with:

python3 --version

Integration Examples

Scripted Transfers

Automate file transfers in bash scripts:

#!/bin/bash
CODE=$(wormhole send "$1" | grep -oP '\d+-[a-z]+-[a-z]+')
echo "Transfer code: $CODE"
echo "Share this with the recipient"

CI/CD Pipeline

Use Magic Wormhole to transfer build artifacts between runners:

wormhole send build/artifacts/*.zip

This avoids setting up temporary file servers or cloud storage for pipeline artifacts.

When to Use Magic Wormhole

Magic Wormhole excels in these scenarios:

Transferring sensitive files between your own machines
Sharing credentials or API keys with team members
Sending encrypted backups without cloud storage
Moving files between networks without exposing them publicly

For permanent file sharing or collaboration, consider combining Magic Wormhole with persistent storage solutions. The tool is designed for one-time transfers, not ongoing file synchronization.

Magic Wormhole provides a practical, terminal-native solution for secure file transfer without the complexity of setting up encrypted channels manually. The short code exchange model makes it accessible while maintaining strong encryption guarantees.

Built by theluckystrike — More at zovo.one