The Rust port of Magic Wormhole adds direct connections and loses Tor

A port, not a rewrite, with a different set of trade-offs

Rusty Wormhole is a Rust port of the Python Magic Wormhole, and the project is explicit about the relationship: it is the Rust implementation of the same idea, and it lists both what it is missing and what it does better.

The premise of the tool is the sentence under the title: get things from one computer to another, safely. The model is that one side starts a wormhole and gets a short, human speakable code, the other side types that code into a client, and the two find each other through a rendezvous server and then exchange data directly or through a relay. The code is short enough to read aloud over a phone call, which is why it works in practice.

The audience for the Rust version is slightly different from the audience for the Python one. The Python project is a command line tool you install. The Rust project is explicitly a library first, with a CLI on top, and the README lists the applications that already use it that way: Warp, a GTK based GUI client, Wormhole File Transfer, an Android client written in Flutter, Wyrmhole, a cross platform GUI built on Tauri, and rvIRC, a vim based IRC client with file sharing.

That list is the strongest evidence about the state of the port. Four independent applications have embedded the library, which means the API has been stable enough for other people to build on, and it means the Rust implementation is not a toy that only its author uses.

The workspace layout reflects the split. The root is the library crate and the cli/ directory is the command line tool, with the workspace defaulting to the CLI member, and the library documentation is generated with cargo doc. The README notes there are no hosted docs at the moment, so the rustdoc is the documentation.

What is missing, and one of those gaps matters

The list of missing features is short, and it is written without hedging.

Text message sending is missing. The Python implementation can send a short text as well as a file, and this port cannot. For most transfers that is irrelevant, since a text is a file in practice, but it does mean the two clients are not feature identical.

Folder sending is missing in the sense that matters. The port can send folders, but it does so by sending a tar ball which the other side has to unpack manually. So the operation succeeds, and the user experience is a tar file rather than a directory.

Tor support is missing, and this is the gap to think about hardest. The Python implementation has a mode that routes the traffic through Tor, which is the natural thing to reach for when the content you are transferring should not touch the network in the clear. The Rust port does not have it, so a user who relies on the anonymous mode of the Python tool has no equivalent here, and the direct connection feature described below makes the absence more consequential rather than less.

That last point is worth stating carefully. The Rust port can make direct connections across the internet, across NATs and firewalls, which means the transfer can complete without relaying through a public relay and without punching a hole through a firewall the user does not control. For a user whose network path matters, that is a meaningful improvement. For a user whose threat model includes hiding the fact that a transfer is happening from their network operator, the missing Tor mode is a real gap and there is no substitute in this repository.

The three missing features are the honest cost of the port, and they are the first thing to check against your own requirements.

Direct connections, clipboard codes, port forwarding and multiple recipients

The list of things the Rust version does beyond the Python one is the reason to prefer it.

It can do direct connections across the internet, across NATs and firewalls. The dependency list explains how. The presence of the STUN codec crate in the workspace dependencies is the trace of a STUN client, which is the standard way to discover your own public address and port behind a NAT, and combined with the noise protocol crates it points at a peer to peer transport rather than a relayed one. For two users on home networks, that turns a transfer that would otherwise be relayed through a server into a direct one.

It automatically copies your code to the clipboard. The arboard crate in the dependency list is the cross platform clipboard library, and the effect on the user is simple and significant: you no longer have to select and copy the wormhole code by hand before pasting it into the other end, which is the step people get wrong.

It does port forwarding in addition to file transfer, marked as experimental. That is a different use of the same machinery: instead of sending a file, you open a local port on one machine and reach it from the other, over the same encrypted channel.

It can send a file to multiple people, also marked experimental, which turns the one-to-one exchange into a one-to-many one and raises the question of how the key material is shared among the recipients.

And it has fuzzy wormhole code completion, which is a quality of life feature with a disproportionate effect on a tool whose main interaction is typing a short code. The wormhole code is a small piece of text that people mistype, and a completion that tolerates a partial or slightly wrong entry removes a genuinely common failure.

Two of these five are labelled experimental in the README, which is the honest way to describe features that are present but not yet finished.

The cryptography and the protocol, as the manifest shows them

The Cargo manifest is unusually informative about how the implementation works, because the dependency list is the protocol.

The key agreement is spake2, the SPAKE2 password authenticated key exchange, which is the algorithm that lets a short human typed code bootstrap a strong shared secret without sending the code itself over the network. The derived key material then goes through hkdf, and the transport uses the noise protocol crates, noise-protocol and noise-rust-crypto, which is the framework that gives the connection its own encryption and authentication. The payload encryption itself uses crypto_secretbox, and the hashes are sha2 and sha-1, with the rand dependency carrying a comment that it depends on the exact version of rand_core used by crypto-common, which is the kind of note that appears when a pin is required for a reason.

Two more dependencies tell you about the user experience rather than the protocol. zxcvbn is a password strength estimator, and qr2term renders a QR code as terminal output, so a transfer can be completed by scanning instead of by reading a code aloud. The CLI is built with clap, the progress display uses indicatif, and the interactive prompts use dialoguer.

The async story is the smol ecosystem, with async-io, async-net, async-fs, async-executor, async-task and futures-lite, plus futures and the derive_more and async-trait crates, and tracing with tracing-subscriber for logging. The relay protocol side uses stun_codec, and the tar crate is there for the folder to tar ball behaviour described earlier.

For interoperation, the README points contributors at the protocol specification in the separate magic-wormhole-protocols repository, and that is the right place to look if you need to know whether a client from this ecosystem can talk to a client from the Python one.

Using the CLI, using the library, hacking on it

The getting started section is brief and splits into three audiences.

If you want to try the CLI, the instruction is cargo run -- --help, and the code sits in ./cli/src with more detail in cli/README.md. The binary is the familiar wormhole interface, and the crate is published to crates.io as magic-wormhole, with the docs on docs.rs.

If you want to use Wormhole in your own application, the instruction is cargo doc --open, and the note that there are no hosted docs at the moment. That is the one documentation gap in an otherwise complete setup: the rustdoc is generated locally, and there is no readthedocs style site to point a new user at.

If you want to contribute, the README points at three files as the approachable entry points: ./src/lib.rs, ./src/transfer.rs and ./src/transit.rs, with the note that they are rather easy to get into, and again the protocol specification as the reference for what the code is supposed to do.

The repository structure supports that layout. There is a src/ directory for the library, a cli/ directory for the command line tool, a tests/ directory, a Cargo.lock, a CHANGELOG.md, a MAINTENANCE.md, a deny.toml for dependency policy checks, a .codecov.yml for coverage reporting, a .rustfmt.toml, a wormhole.1 man page, and a .cargo/ directory. The build badges cover the Rust workflow, the dependency status through deps.rs, the codecov coverage, an is-it-maintained resolution time badge, and the crates.io and docs.rs versions.

The toolchain requirements are Rust 1.92 and edition 2024, so this is a project that needs a current compiler.

The licence is the decision, not the code

The licence is the European Union Public Licence v1.2 or later, and the README adds a sentence that decides the project for some adopters: contact the owner(s) for use in proprietary software.

The EUPL is a copyleft licence designed to be compatible with the GPL, and the practical effect for a commercial product is not the same as MIT or Apache. A company shipping a closed source application that embeds this library is not in the clear without a conversation with the owners, and the README tells you to have it. That is a licensing step, not a legal formality, and it is the first thing to check if you are evaluating the library for a product.

For everything else, the maintenance picture is steady. The current version is 0.8.1, published on 2026-05-07, with 0.8.0 the day before and 0.7.7 in March, so the release line is moving. The last push was on 2026-07-22 and the repository is not archived. The crate description in the manifest is the same one line as the title, get things from one computer to another, safely, with the authors listed as Fina Wilke, piegames and Brian Warner, the last of whom being one of the people behind the original protocol.

The MAINTENANCE.md file at the root, alongside the CHANGELOG and the deny.toml, is the sort of thing a project that wants to be taken over eventually writes down, and combined with the active issue tracker, the Matrix room on the magic-wormhole channel and the IRC channel on Libera, the project has the visible signs of a maintained open source project rather than a personal script.

For a user of the tool rather than a developer, the practical picture is simple: a single static binary, a short code to read out loud, and a direct connection when the network allows it, with the caveats above being the ones to check against how you intend to use it.

Editorial conclusion

The Rust implementation suits a developer who wants Magic Wormhole as a library inside a desktop application, and it suits a user behind a NAT or firewall who wants the transfer to connect directly rather than relay. It is the wrong choice if you need Tor anonymity, because the port does not implement it, and a poor match for a commercial product, because the EUPL v1.2 licence requires you to contact the owners for use in proprietary software. Before adopting, read the licence terms in the repository, check whether your platform has an application built on the library, and plan to interoperate with the Python implementation through the published protocol specification rather than assuming the two are interchangeable in every mode.

Frequently asked questions

Official sources

1. Issues
2. License: EUPL-1.2
3. magic-wormhole/magic-wormhole.rs on GitHub
4. README
5. Releases