How to Install and Use Magic Wormhole in Linux for Encrypted CLI File Transfers

Transferring files between two computers on different networks has traditionally required convoluted workarounds: setting up temporary cloud storage links, configuring public SSH keys, forwarding firewall ports, or sending sensitive archives through unencrypted email attachments. While utilities like scp and rsync are exceptional for routine server administration, they require public IP visibility or direct networking connectivity between endpoints.

To make terminal-to-terminal file sharing effortless and completely secure, Magic Wormhole (invoked simply as wormhole) provides a cryptographic peer-to-peer file transfer utility. Magic Wormhole uses a public rendezvous relay to negotiate a direct peer-to-peer connection encrypted with SPAKE2 (Simple Password Exponential Key Exchange). To connect two machines, users share a human-memorable, single-use code phrase consisting of a short number and two common English words (such as 7-guitarist-revenge). This guide explains how to install Magic Wormhole on Linux, transfer files and directories, send encrypted text snippets, and verify connection authenticity.

How Magic Wormhole Operates Behind the Scenes

Magic Wormhole blends high-grade cryptography with approachable human usability:

• Human-Friendly Code Phrases: Rather than exchanging long hexadecimal cryptographic fingerprints, the sender generates a short code phrase (e.g., 4-emerald-dragon) that can be read over the phone, texted, or dictated in conversation.
• Strong Mutual Authentication: The code phrase acts as a one-time password to derive an ephemeral, high-entropy cryptographic key using the SPAKE2 key exchange algorithm. An eavesdropper monitoring the rendezvous server cannot decrypt the data payload.
• Automatic Direct P2P Tunneling: Once the key exchange completes, Magic Wormhole attempts to establish a direct TCP connection across local subnets or via WebRTC NAT traversal. If direct connection fails due to strict corporate firewalls, encrypted transit traffic routes through a secure transit relay.
• Directory Compression and Streaming: Automatically compresses directories into transit archives on the fly and decompresses them seamlessly at the destination.

How to Install Magic Wormhole on Linux

Magic Wormhole is packaged in the standard repositories of almost all major Linux distributions, as well as via Python’s package manager.

Method 1: Installing via Native Package Managers

On Ubuntu, Debian, or Linux Mint:

sudo apt update && sudo apt install magic-wormhole -y

On Fedora:

sudo dnf install magic-wormhole -y

On Arch Linux:

sudo pacman -S magic-wormhole

Method 2: Installing via Pip / Pipx

If you prefer an isolated Python environment or need the latest upstream build:

pipx install magic-wormhole

Verify installation by checking the utility version:

wormhole --version

How to Send and Receive Files Between Two Terminals

The standard workflow requires one user to initiate the send command and the recipient to enter the matching wormhole code.

Step 1: Sending a File from Machine A

To transmit a document or archive, invoke wormhole send followed by the file path:

wormhole send project_backup.tar.gz

Magic Wormhole will contact the public rendezvous server, allocate an ephemeral channel, and output a prompt:

Sending 45.2 MB file named 'project_backup.tar.gz'
Wormhole code is: 12-coastal-badger
On the other computer, please run:
wormhole receive 12-coastal-badger

Step 2: Receiving the File on Machine B

On the destination Linux computer (or any macOS/Windows machine running Magic Wormhole), execute the generated command:

wormhole receive 12-coastal-badger

The client will authenticate the cryptographic handshake and prompt the user to confirm the incoming file size and filename:

Receiving file (45.2 MB) into: project_backup.tar.gz
ok? (y/N): y

Type y and press Enter. Magic Wormhole will negotiate the fastest available peer-to-peer route, display a live progress bar, verify file integrity with SHA-256 hashes, and terminate the session upon completion.

Sending Entire Directories and Encrypted Text Snippets

Beyond individual files, Magic Wormhole handles folders and confidential credentials cleanly:

Sending Entire Folder Trees

To transfer a complete directory containing subfolders and assets:

wormhole send ~/Projects/webapp/

Magic Wormhole will zip the folder in memory, stream the compressed archive across the encrypted channel, and unpack it automatically in the recipient’s working directory.

Sending Ephemeral Text Messages or Passwords

If you need to share a database password, private API token, or SSH key securely without leaving permanent records in messaging chat logs:

wormhole send-message "db_pass_secret_2026!"

The recipient runs wormhole receive <code>, and Magic Wormhole prints the decrypted text directly into their terminal without saving anything to disk.

Security Considerations and Transit Privacy

Keep these operational rules in mind when relying on Magic Wormhole:

• Single-Use Security: Code phrases are valid for exactly one transfer attempt. If an attacker attempts to guess the code phrase, the rendezvous server permits only a single failed guess before destroying the channel entirely.
• End-to-End Encryption: The central relay servers run by the open-source community act only as blind connection brokers; they cannot read transferred files, metadata, or message payloads.
• Self-Hosted Relay Option: Organizations operating in zero-trust corporate environments can run their own private rendezvous and transit relay daemons using the wormhole-server package and pass the --relay-url flag to internal clients.