Last updated: March 16, 2026

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.

Table of Contents

Prerequisites

Before you begin, make sure you have the following ready:

Step 1 - 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.

Step 2 - Install ation

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

Step 3 - 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).

Step 4 - 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.

Step 5 - 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.

Step 6 - 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:

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

Step 7 - 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:

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.

Troubleshooting

Configuration changes not taking effect

Restart the relevant service or application after making changes. Some settings require a full system reboot. Verify the configuration file path is correct and the syntax is valid.

Permission denied errors

Run the command with sudo for system-level operations, or check that your user account has the necessary permissions. On macOS, you may need to grant terminal access in System Settings > Privacy & Security.

Connection or network-related failures

Check your internet connection and firewall settings. If using a VPN, try disconnecting temporarily to isolate the issue. Verify that the target server or service is accessible from your network.

Frequently Asked Questions

How long does it take to send files?

For a straightforward setup, expect 30 minutes to 2 hours depending on your familiarity with the tools involved. Complex configurations with custom requirements may take longer. Having your credentials and environment ready before starting saves significant time.

What are the most common mistakes to avoid?

The most frequent issues are skipping prerequisite steps, using outdated package versions, and not reading error messages carefully. Follow the steps in order, verify each one works before moving on, and check the official documentation if something behaves unexpectedly.

Do I need prior experience to follow this guide?

Basic familiarity with the relevant tools and command line is helpful but not strictly required. Each step is explained with context. If you get stuck, the official documentation for each tool covers fundamentals that may fill in knowledge gaps.

Is this approach secure enough for production?

The patterns shown here follow standard practices, but production deployments need additional hardening. Add rate limiting, input validation, proper secret management, and monitoring before going live. Consider a security review if your application handles sensitive user data.

Where can I get help if I run into issues?

Start with the official documentation for each tool mentioned. Stack Overflow and GitHub Issues are good next steps for specific error messages. Community forums and Discord servers for the relevant tools often have active members who can help with setup problems.

Related Articles