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:
- No requirement to set up or trust a relay server for authentication.
- Powered by WireGuard for secure, fast, and reliable connections.
- Automatic peer-to-peer connections over UDP.
- 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:
- Slow speeds due to relay servers.
- Trusting a 3rd party server for authentication.
- 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
- Tailscale
- Headscale
- WireGuard-go
