SSH through any firewall.
Connecting to a machine behind a NAT or firewall is a pain. Port forwarding, VPNs, reverse tunnels, a bastion host you keep forgetting to patch. Pigeons punches through all of it using public keys, so you can ssh to any machine, wherever it is.
IP addresses break, use keys instead.
Installation
Install pigeons with our bash one-liner:
server: Start listening
Start a roost to accept incoming connections. Pigeons will generate an ID, which is an Ed25519 public key. These IDs are persisted by default so they stay the same across restarts:
$ pigeons roost
roost is running! id: bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330
Client: add a route and fly
Add a pigeon route, which writes an entry to your SSH config, then connect with plain old ssh:
$ pigeons add --id bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330 --name my-server
Pigeon route 'my-server' added to ~/.ssh/config
$ ssh user@my-server
Works regardless of where the two machines are.
The pigeon always finds its way home.
Always-on roosts
Install pigeons as a system service so the roost is always ready for incoming connections — on Linux (systemd), macOS (launchd), and Windows (SCM):
pigeons service install # default SSH port 22
pigeons service status # check if it's running
pigeons service log # view service logs
pigeons server uninstall # remove the service
Built on Iroh
Under the hood, pigeons is a thin wrapper around the iroh rust crate. SSH's ProxyCommand shells out to pigeons fly --stdio, which opens a QUIC connection through iroh's peer-to-peer network with automatic NAT traversal, and the roost proxies it to the local SSH daemon. You can build the same kind of connection into your own app with the iroh Endpoint.
QUIC all the way down
Standard SSH authentication runs end-to-end over an encrypted QUIC tunnel. Your keys, certificates, and passwords all work exactly as they do today — pigeons just handles getting the bytes to the other machine. It's UDP-based, stream-multiplexing, and encrypted; the pigeon carries the letter, it doesn't read it.
Sometimes you gotta relay
For some small percentage of connections, it's simply not possible to connect two devices directly. For those cases, iroh uses a meshed network of relay nodes to pack up UDP traffic & send it over HTTP. Sounds silly, but it works! Iroh handles all this under the hood.
A word on security
Anyone with your endpoint ID can reach your SSH port — so standard SSH authentication (keys, certificates, passwords) is what actually guards the door. Pigeons uses a dedicated ~/.ssh/pigeons_ed25519 keypair and QUIC transport encryption between endpoints. The letter is only as safe as the lock on your door; pigeons makes sure it arrives.