ferry
Send files and messages between two machines, yours and a friend's.
No accounts, no port forwarding, end-to-end encrypted.
ferry send ./build.tar.zst
It prints a code like 7-acorn-tulip-otter. On the other machine:
ferry get 7-acorn-tulip-otter
That is the whole thing. The file goes straight from one machine to the
other as fast as the slower connection allows, survives a dropped Wi-Fi,
resumes if interrupted, and is checked byte for byte on arrival.
Pair once, then use names
ferry pair # prints a code; the friend runs: ferry pair <code>
ferry send sam ./photos # from now on, no codes
ferry msg sam "pushed branch x, have a look"
ferry inbox
ferry wait --from sam --timeout 10m
Messages reach a friend who is offline too: they wait, sealed, in a
mailbox until the friend is next online. Files need both machines online;
ferry up keeps a machine reachable in the background.
For Claude Code and other agents
ferry is an MCP server:
claude mcp add ferry -s user -- ferry mcp
Two Claude Code sessions on two machines can then message each other,
wait for replies, and hand over files and patches. The tools are
send_message, read_messages, wait_for_message, send_file,
list_files_received, fetch_file, list_contacts and channel_status.
Shell-only agents get the same through the CLI: every command takes
--json, writes one JSON event per line to stdout and progress to stderr,
never prompts, and exits with a meaningful code (ferry help exit-codes).
ferry help --llm prints a one-page manual written for a model.
What arrives through ferry is data from someone else. ferry never runs
it, fetched files lose their execute bit, and the MCP server tells the
model to treat received text as untrusted.
Install
One static binary for Linux and macOS:
go install github.com/ZahakJ/ferry/cmd/ferry@latest
To reach each other across the internet, two machines need a rendezvous
server to introduce them, and a way through their routers. Run your own
rendezvous (deploy/fly has the steps for fly.io; any machine
with a public address works) and point both machines at it:
ferry config rendezvous /dns/rv.example.org/tcp/4001/p2p/12D3KooW...
If a router blocks the direct connection, forward one UDP port to the
machine behind it and tell ferry to use it:
ferry config port 40000
ferry check
ferry check says what works and what does not: the rendezvous, your
public address, the port.
STUN (how each machine learns its public address) defaults to a public
server. To use your own, set FERRY_STUN=stun:stun.example.org:3478, or
"stun": ["stun:…"] in config.json in ferry config's folder.
SSH to a paired machine
ferry pipe connects stdin/stdout to a TCP port on a contact's localhost,
over the same direct, end-to-end encrypted link, with no open ports on
either side. On the machine to reach, allow exactly the ports you mean
(nothing is allowed by default; every pipe is logged):
ferry up --allow-pipe 22
On the other, after pairing:
ssh -o ProxyCommand='ferry pipe box 22' me@box
# or in ~/.ssh/config: Host box
# ProxyCommand ferry pipe box 22
If the other side allows exactly one port, ferry pipe box alone reaches
it. With ferry up running here, pipes go through it.
How it works
- Meeting. Both sides connect out to the rendezvous. The code's
number is a meeting slot there; its words never leave your machine.
- Agreeing on a key. The two sides run CPace, a password-authenticated
key exchange, over the words. Someone watching, or the rendezvous
itself, learns nothing about them, and a wrong guess burns the code:
one try, then both sides stop.
- Connecting. Sealed under that key, they swap WebRTC offers. Those
carry the fingerprints of the encryption keys the data connection will
use, so nobody in the middle can substitute their own. Then ICE punches
through both NATs. Data only ever goes directly between the two
machines; if no direct path exists, ferry says so and stops.
- Moving data. The transfer is split across several connections at
once (one alone recovers slowly from loss on long paths). Each piece
carries a BLAKE3 hash and each file is hashed whole; nothing gets its
real name until it matches.
Pairing does the same once and then swaps long-term keys. Later sessions
between contacts authenticate with those keys instead of a code.
The rendezvous is not trusted with anything but availability. The
threat model spells out what it and others can and cannot
do.
Speed
Measured by the test harness (test/harness.sh): two machines, each behind
its own NAT, on one 16-core Linux box; netem shapes the path.
| path | ferry | one TCP stream |
|---|
| loopback, one machine | 2.0 Gbps | |
| LAN-like, through both NATs | 1.2–3.3 Gbps | |
| 40 ms round trip | 0.9–2.1 Gbps | 0.8 Gbps |
| 40 ms round trip, 0.5% loss | 0.64–0.69 Gbps | 0.4 Gbps |
Ranges are across runs; both ends share one machine's CPUs, so real
machines on a real LAN do better.
How the numbers were found and what was tuned: docs/throughput.md.
Tested
test/harness.sh builds two NATed homes, a rendezvous and a STUN server
inside a user namespace (no root needed) and checks: pairing; a wrong code
rejected on both sides; a direct path through both NATs; a plain "no
direct path" when UDP between them is blocked; a forwarded port through
strict NATs; no plaintext anywhere on the wire, rendezvous included; a
20 GiB file (FERRY_HARNESS_BIG=20480) killed part way over a 40 ms, lossy path and resumed with a
matching hash; and two MCP clients exchanging messages and a file.
Tested with 20 GiB files. Offsets are 64-bit and nothing holds a whole
file in memory: during a 20 GiB transfer the sender used under 200 MB of
RAM and the receiver about 130 MB.
License
MIT
