Your submission was sent successfully! Close

Jump to main content
  1. Blog
  2. Article

Igor Ljubuncic
on 21 March 2019

Magic Wormhole – Send files with ease

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.

Related posts

Holly Hall
30 June 2023 reloaded: check out the new look and feel

Ubuntu Article

We’re happy to announce that has a fresh, new look! Time for an update After keeping the same user interface and style for several years, we embarked on a project to redesign and give it a more modern look. We spent a lot of time analysing how we could improve the store and ...

Heather Ellsworth
27 June 2023

Improving snap maintenance with automation

Desktop Article

Co-written with Sergio Costas Rodríguez. As the number of snaps increases, the need for automation grows. Any automation to help us maintain a group of snaps is welcome and necessary for us to be able to scale. The solution detailed in this article has two main benefits: Any users of snaps that have adopted this ...

Igor Ljubuncic
16 June 2023

Snapcraft 8.0 and the respectable end of core18

Ubuntu Article

‘E’s not pinin’! ‘E’s passed on! This base is no more! He has ceased to be! ‘E’s expired and gone to meet ‘is maker! ‘E’s a stiff! Bereft of life, ‘e rests in peace! If you hadn’t nailed ‘im to the perch ‘e’d be pushing up the daisies! ‘Is software processes are now ‘istory! ‘E’s ...