The Magic-Wormhole Ecosystem

This page attempts to summarize the current state of various codebases that implement or extend the Magic Wormhole protocols. If you feel something is missing, please open an Issue or (better yet) a Pull Request at https://github.com/magic-wormhole/magic-wormhole

This document represents our best knowledge as of September, 2023.

Documentation

There are many documents in this repository itself, which tend to be more Python-specific. The Magic Wormhole Protocols repository aims to collect programming-language-agnostic documentation and specifications of the core Magic Wormhole protocol and extensions. Currently, it is still not complete, and sometimes fails to describe existing features or describes enhancements that don’t yet have an implementation.

Rendered versions of this document exist at magic-wormhole.readthedocs.io.

Protocols Overview

There are several main pieces of the protocol:

  • the core “mailbox protocol”, spoken via the mailbox server (formerly called “rendezvous server” in some places) and client implementations
  • the “transit relay” protocol, spoken by the transit relay server
  • the Dilation protocol (which depends on the core mailbox protocol), spoken by client implementations

It is possible for clients to specify zero or many Transit Relays, but both peers must use the same Mailbox Server to successfully communicate (even if they end up with a direct, non-relay connection).

This document does not try to describe any of these protocols in detail.

Implementations and Support

There are several main features of the core protocol; while implementations strive for completeness, we document here what features those implementations actually support.

The only known Mailbox Server is https://github.com/magic-wormhole/magic-wormhole-mailbox-server The only known Transit Relay implementation is https://github.com/magic-wormhole/magic-wormhole-transit-relay

The Dilation protocol itself is still in development (with a basically-complete Python implementation, a servicable specification and an in-development Rust implementation).

The “Seeds” extension is a plan with no known implementations or specifications

The “Permissions” extension has a “proof-of-concept” Python client and server implementation and a specification but is not in any releases.

Features Supported by Implementations

The separate features represented in the below table are:

  • Core: the basic client-visible features of the core mailbox protocol to open, allocate, claim and close a mailbox (as well as add messages to it)
  • Reconnect: client state and behavior to re-connect to an in-progress or existing mailbox (e.g. in case of network failure, etc)
  • File Transfer v1 (“File v1”): the exsting file-transfer protocol (allowing single Files or Directories or text-messages to be transferred in one direction)
  • Permissions: an extension to allow the server to request additional work or information from clients before allowing access.
  • Dilation: the core Dilation protocol
  • Dilated File Transfer (“Dilated Transfer”): a more fully-featured file-transfer protocol on top of Dilation.

Support is described as:

  • Full: supports the feature
  • Partial: supports the feature, with some caveats
  • Experimental: supports the feature fully, but not quite final (e.g. needs flags to turn on, API may change, etc)
  • PoC: some level of implementation exists, but not enough to be considered “Experimental”.
  • No: the feature is not supported
Implementation Support
Language Core Reconnect File v1 Dilation Dilated Transfer
Python Full Full Full Experimental PoC
Rust Full Partial Partial PoC No
Haskell Full No Full No No
Go Full ??? Full No No

Notes: * the Rust implementation v1 file-transfer doesn’t support text-messages, or directory transfer (although it will produce a tarball and send it, that is not automatically unpacked on the other side) * there are two parts to the Haskell implementation: a library, and a Haskell file-transfer CLI client

End User / Client Applications

Based on the above libraries, there are several end-user applications targeting different platforms. Unless otherwise noted, these “inherit” any limitations of their langauge’s library implementation from the above table.

Library and CLI

GUIs for Desktop, Mobile, Web

  • Warp is a GNOME GUI written in Rust
  • Winden is a Web client and deployment (using the Go implemtation via WASM)
  • Destiny is an Android (and iOS) app using Flutter (with the Go implementation for wormhole). Also on proprietary app stores.
  • Wormhole for Android. Based on the Rust implementation.
  • Mobile Wormhole for Android (also on f-droid. Based on the Python implementation, using Kivy
  • Wormhole William Mobile for Android and iOS.
  • Rymdport is a cross-platform graphical desktop application based on wormhole-william.

Integrations

These use the basic file-transfer functionality of the protocol, but build it in to some other application.

  • tmux-wormhole a tmux plugin allowing use of file-transfer from within a tmux session (based on the Go implementation).
  • termshark integrates wormhole-william (the Go implementation) to facilitate transfer of .pcap files (see the termshark User Guide

Other Uses

Some other interesting uses of Magic Wormhole that don’t directly use the file-transfer protocol. If you know of others, please send them along!

  • Port-forwarding: over the classic Transit protocol in the rust implementation and over the Dilation protocol in Python as fow (foward-over-wormhole).
  • Invite / key-exchange: Magic Folder implements a custom protocol to do “introduction” / key-exchange.
  • Invite / configuration exchange: Tahoe-LAFS uses Magic Wormhole to exchange configuration (and keys) for participants to join a Grid.