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


在过去几个月我们发布了一些如何使用Rust,Java,C/C++和其他语言来开发snap桌面应用的文章。在这些从入门到精通的教程中,我们以一个代表性的snapcraft.yaml文件来介绍开发构建snap所需的具体细节。 今天,我们希望脱离这一过程,而将重点放在服务器端。我们将为你提供一个包含两个有趣组件的snapcraft.yaml的概述:a)它将拥有多个应用程序; 通常,snap包含一个应用程序。b)它具有简单的后台服务,其他应用程序可以连接到该服务。 我们一起来看一下。 Snapcraft yaml 以下是snapcraft.yaml文件的内容: apps: borg: command: bin/borg daemon: simple restart-conditi […]

Learn snapcraft by example – multi-app client-server snap

Over the past few months, we published a number of articles showing how to snap desktop applications written in different languages – Rust, Java, C/C++, and others. In each one of these zero-to-hero guides, we went through a representative snapcraft.yaml file and highlighted the specific bits and pieces developers need to successfully bui […]

Snapcraft tricks: Improve release flexibility with pull and build overrides

Sometimes, software projects are simple – one architecture, one version, one release. But often, they can be complex, targeting multiple platforms, and with different versions at that. If you are packaging your apps as snaps, you might wonder about the optimal way to accommodate a multi-dimensional release matrix. One yaml to rule them al […]