Magic Wormhole – Send files with ease

by Igor Ljubuncic on 21 March 2019

Sharing is caring.

Alexander the Great

File transfer is the bread and butter of information exchange in the digital world. Documents, photos, videos, we share them with our colleagues and friends. The only problem is, the Internet is a global village with many languages – and we’re talking about software, not humans.

If you want to share a file with someone, typically, both you and the recipient need to use the same tools to do this successfully. Email works well for most people, but usually, there are arbitrary limits of the attachment size. Online sharing services that create download links are another useful possibility, and these do address most of the limitations of the multi-software mishmash that exists out there. For Linux users, there’s a third possibility – Magic Wormhole.

How does it work?

Magic. Well almost. User A simply “sends” the file they want. Before the content is actually sent, a short, simple-to-remember (or rather simple-to-repeat) password phrase is generated. User A then shares this phrase with whoever needs to receive the file on the other end. User B needs to type down this password when prompted by the Magic Wormhole tool. Once this step is complete, the file will be transferred between the two users, and there will be much rejoicing.

You can test for yourself. First, install Magic Wormhole.

snap install wormhole

Wormhole has a command-line interface. On system A, send a file – or even an entire directory if you like. The application will zip it up, and the directory contents will be unpacked automatically at the other end. Something like:

wormhole send "Hans Gruber quotes.ogg"
Sending 12.9 MB file named 'Hans Gruber quotes.ogg'
Wormhole code is: 9-virginia-ratchet
On the other computer, please run:

wormhole receive 9-virginia-ratchet

As you can see, the tool will let you know the password that you need to supply to the other party. On their system, the intended recipient can then type:

wormhole receive 9-virginia-ratchet

Both systems need to be online when this happens. If the source is not available, the transfer cannot run. If you’re testing this on your own, you can watch the file progress in the two terminal windows in parallel.

And that’s it.

There’s no such thing as magic!

Of course, under the hood, a lot of interesting things happen. The developer of the tool gave a PyCon 2016 presentation on his work, and the official documentation includes additional details on how Magic Wormhole functions.

In essence, there are three main components to the program. The interesting piece is the so-called Rendezvous Server (a WebSocket relay), which acts as a negotiator between the two endpoints – hence the name, wormhole. When the sender initiates the transfer, it will generate a cryptographic key pair (will be used to encrypt data during the transfer), contact the Rendezvous Server and supply the session key, as well as the sender IP address and port number for the connection. When the recipient contacts the server (with the correct password provided), it will send its half of the information over (including the correct session key) so that the two endpoints can be hooked together.

The transfer will then run – directly between the two systems if they can reach other directly. However, if the IP addresses or ports are not accessible (due to firewall or NAT), then the exchange of data will run through the relay. This also explains why both systems need to be running wormhole at the same time, because the data is not sent in advance and buffered, it is transferred in real-time once both sides negotiate their ends of the connection.

So if you’re wondering, yes, there might be network throughput limitations, especially if there are many transfers running simultaneously over the relay. The Rendezvous Server address is hard-coded into wormhole, but you can setup your own infrastructure if you want. The security model is relatively robust against eavesdropping, but like any sharing service, you do need to trust the infrastructure over which you’re sending information – you can always encrypt the data yourself.

Perhaps this is no magic, but it’s a pretty neat trick.


If you’re a technically savvy person, i.e. you can comfortably use the command line to manipulate files, then Wormhole Magic is a nice, flexible tool that can help you share content with other people in a rather secure manner. Should you have any feedback on comments on this topic, please join our forum, and let us know what you think.

No laws of physics or time-space continuum dimensions were harmed in the writing of this article.

Photo by Kamesh Vedula on Unsplash.

Newsletter Signup

Related posts

Creating Snaps on Ubuntu Touch

This article was written in collaboration with Alfred E. Neumayer of the UBports Project. Tablets, phones and current technology’s capabilities are phenomenal. Who would have thought a thin, light, barely 10 inch device would provide all the power necessary to run Virtual Machines, wherever one desires while powered on battery? That a sma […]

Managing software in complex network environments: the Snap Store Proxy

As enterprises grapple with the evolving landscape of security threats, the need to safeguard internal networks from the broader internet is increasingly important. In environments with restricted internet access, it can be difficult to manage software updates in an easy, reliable way. When managing devices in the field, change management […]

We wish you RISC-V holidays!

There are three types of computer users: the end user, the system administrator, and the involuntary system administrator. As it happens, everyone has found themselves in the last group at some point or another; you sit down to perform a task relevant to your needs or duties, but suddenly the machine does not work as […]