Magic Wormhole

Magic Wormhole is a peer-to-peer file transfer protocol. It uses a short code to establish a direct connection between two devices to securely transfer files.

To send a file using the wormhole CLI:

1. wormhole send filename
2. Get the code (something like 8-pharmacy-indoors) to the other device (which also must have a magic wormhole client installed):
   • Scan the QR via the relevant app, or
   • Type the code into an app, or
   • Run wormhole receive 8-pharmacy-indoors (replace with your actual code)

You can easily communicate the code by voice or any other secure channel, since it's short - always a number and two words. It is easy to copy-paste, since double click selects it in some/most shells as it's separated by dashes.

The protocol guarantees that unless an attacker can intercept the code you share, they cannot intercept the file you share (unless they get an unreasonably lucky guess; a failed guess cancels the send, so attacks would be very visible and very low odds to succeed).

Also useful for sending ssh public keys via wormhole ssh invite from the server then wormhole ssh accept ... on the system which would like to send a key. wormhole ssh accept ... requires selecting the public key to send if there is more than one.

Install

Install magic-wormhole for the CLI.

It is more convenient to use the default servers, and the protocol provides security guarantees independent of the servers used, so the overwhelming majority of users should reasonably prefer to not run their own infrastructure. However, you can run your own if for example you are developing your own app based on the service, or wish to dedicate bandwidth to the public. To do so, install python-magic-wormhole-mailbox-server and/or python-magic-wormhole-transit-relay.

Relay configuration

Create and enable/start the following systemd units.

/etc/systemd/system/wormhole-mailbox.service

[Unit]
Description=Magic Wormhole Mailbox Server
After=network.target

[Service]
ExecStart=/usr/bin/twist --log-format=text wormhole-mailbox --channel-db=/var/lib/magic-wormhole-mailbox-server/relay.sqlite
DynamicUser=yes
StateDirectory=magic-wormhole-mailbox-server
RestrictNamespaces=yes
SystemCallFilter=@system-service
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

/etc/systemd/system/wormhole-relay.service

[Unit]
Description=Magic Wormhole Transit Relay
After=network.target
 
[Service]
ExecStart=/usr/bin/twist --log-format=text transitrelay
DynamicUser=yes
RestrictNamespaces=yes
SystemCallFilter=@system-service
Restart=on-failure
 
[Install]
WantedBy=multi-user.target

Using your relay depends on the client - for the refrence `wormhole` CLI client: wormhole --relay-url=ws://server:4000/v1 --transit-helper tcp:server:4001 send file - replace the ports if you use non-default ports. Alternatively, export the WORMHOLE_RELAY_URL and WORMHOLE_TRANSIT_HELPER environment variables, set to equivalent values.