wush

wush is a command line tool that lets you easily transfer files and open shells over a peer-to-peer WireGuard connection. It's similar to magic-wormhole but:

1. No requirement to set up or trust a relay server for authentication.
2. Powered by WireGuard for secure, fast, and reliable connections.
3. Automatic peer-to-peer connections over UDP.
4. Endless possibilities; rsync, ssh, etc.

Basic Usage

On the host machine:

$ wush serve
Picked DERP region Toronto as overlay home
Your auth key is:
    >  112v1RyL5KPzsbMbhT7fkEGrcfpygxtnvwjR5kMLGxDHGeLTK1BvoPqsUcjo7xyMkFn46KLTdedKuPCG5trP84mz9kx
Use this key to authenticate other wush commands to this instance.

On the client machine:

# Copy a file to the host
$ wush cp 1gb.txt
Uploading "1gb.txt" 100% |██████████████████████████████████████████████| (2.1/2.1 GB, 376 MB/s)

# Open a shell to the host
$ wush ssh
┃ Enter the Auth key:
┃ > 112v1RyL5KPzsbMbhT7fkEGrcfpygxtnvwjR5kMLGxDHGeLTK1BvoPqsUcjo7xyMkFn46KLTdedKuPCG5trP84mz9kx
coder@colin:~$

[!NOTE]
wush uses Tailscale's tsnet package under the hood, managed by an in-memory control server on each CLI. We utilize Tailscale's public DERP relays, but no Tailscale account is required.

Install

Using install script

curl -fsSL https://github.com/coder/wush/raw/refs/heads/main/install.sh | sh

Using Homebrew

brew install wush

For a manual installation, see the latest release.

[!TIP] To increase transfer speeds, wush attempts to increase the buffer size of its UDP sockets. For best performance, ensure wush has CAP_NET_ADMIN. When using the installer script, this is done automatically for you.

# Linux only
sudo setcap cap_net_admin=eip $(which wush)

Technical Details

wush doesn't require you to trust any 3rd party authentication or relay servers, instead using x25519 keys to authenticate incoming connections. Auth keys generated by wush serve are separated into a couple parts:

112v1RyL5KPzsbMbhT7fkEGrcfpygxtnvwjR5kMLGxDHGeLTK1BvoPqsUcjo7xyMkFn46KLTdedKuPCG5trP84mz9kx

+---------------------+------------------+---------------------------+----------------------------+
| UDP Address (1-19B) | DERP Region (2B) |  Server Public Key (32B)  |  Sender Private Key (32B)  |
+---------------------+------------------+---------------------------+----------------------------+
| 203.128.89.74:57321 |               21 | QPGoX1GY......488YNqsyWM= | o/FXVnOn.....llrKg5bqxlgY= |
+---------------------+------------------+---------------------------+----------------------------+

Senders and receivers communicate over what we call an "overlay". An overlay runs over one of two currently implemented mediums; UDP or DERP. Each message over the relay is encrypted with the sender's private key.

UDP: The receiver creates a NAT holepunch to allow senders to connect directly. WireGuard nodes are exchanged peer-to-peer. This mode will only work if the receiver doesn't have hard NAT.

DERP: The receiver connects to the closet DERP relay server. WireGuard nodes are exchanged through the relay.

In both cases auth is handled the same way. The receiver will only accept messages encrypted from the sender's private key, to the server's public key.

Why create another file transfer tool?

Lots of great file tranfer tools exist, but they all have some limitations:

1. Slow speeds due to relay servers.
2. Trusting a 3rd party server for authentication.
3. Limited to only file transfers.

We sought to utilize advancements in userspace networking brought about by Tailscale to create a tool that could solve all of these problems, and provide way more functionality.

Acknowledgements

1. Tailscale
2. Headscale
3. WireGuard-go