Wanted to share a project I have been working on for a while https://github.com/holesail/holesail
It is a lightweight reverse proxy similar to Ngrok but works over peer-to-peer tunnels and requires absolutely no configuration.
No port forwarding, no VPNs, no servers in the middle just a direct, end-to-end encrypted connection between two peers using a simple connection key.
It supports both UDP and TCP and runs on Linux, Mac, Windows, Android and iOS and has a Node API that can be used to integrate it into any Android, iOS or CLI app.
The goal is to make Holesail the go-to solution for developers, and self hosters who need fast, reliable, private connectivity.
Some of the stuff I use it for: 1. Accessing self hosted services such as Immich, Vaultwarden, Jistsi Meet, Paperless ngx, Portainer, Filegator 2. Playing LAN games over the internet, like Minecraft and Stardew valley 3. SSHing into my servers 4. Server security
Features: 1. Cross platform i.e. Android, iOS, Linux, Windows, Mac 2. Open source 3. Supports both TCP and UDP 4. Unlimited traffic (as much as your router and server can support) 5. Unlimited bandwidth (as much as your ISP gives you) 6. No servers 7. No accounts 8. Not a vpn 9. Can punch through firewalls and CGNAT 10. Integrate into other apps with Node API
It is the perfect alternative to Tailscale, Cloudflared, Ngrok or any other tunneling tool that otherwise works over ssh or servers.
Would love to hear feedback from anyone working with networking, P2P systems, or tunneling tools.
Happy to answer any questions!
Thanks
mutant•2mo ago
it might be wtong but i wouldve had to invest significant time to understand your networking model without it.
-----
## Holesail Connection & Encryption Architecture
### Core Technology Stack
Holesail is built on top of *Holepunch’s Hyperswarm* ecosystem, specifically:
1. *HyperDHT* - Kademlia-based distributed hash table for peer discovery 1. *Hyperswarm* - High-level P2P networking abstraction 1. *@hyperswarm/secret-stream* - Noise Protocol + libsodium encryption layer 1. *UDX* - Custom UDP transport protocol
-----
### Connection Technique: UDP Holepunching
*How it works:*
1. *Peer Discovery via DHT*: When you run `holesail --live <port>`, the server generates an *Ed25519 keypair* and announces its public key to the HyperDHT. The connection string (`hs://...`) is essentially this public key encoded. 1. *NAT Traversal*: The DHT nodes themselves act as holepunch facilitators. Unlike traditional STUN/TURN servers, any peer in the DHT can help coordinate the holepunch between two NAT’d peers. This is what makes it “truly P2P” - no centralized relay infrastructure. 1. *Holepunch Mechanics*:
- Both peers send UDP packets to each other’s external IP:port (discovered via DHT) - The simultaneous outbound packets “punch” holes in both NATs - The DHT nodes relay timing/coordination metadata - Once holepunched, a direct UDP connection is established
1. *Transport*: Uses *UDX* (custom UDP protocol) for the data plane after holepunching. TCP fallback is available when UDP fails.
-----
### Encryption Management
*Two-layer encryption using Noise Protocol + libsodium secretstream:*
|Layer |Protocol |Purpose | |---------|--------------------------|------------------------------------| |Handshake|*Noise XX pattern* |Key exchange, mutual authentication | |Data |*libsodium secretstream*|Symmetric encryption of all payloads|
*Cryptographic Primitives:*
- *Key generation*: Ed25519 keypairs (identity/authentication) - *Key exchange*: Noise Protocol XX pattern (ephemeral DH) - *Symmetric encryption*: XChaCha20-Poly1305 (via libsodium secretstream) - *Handshake hash*: Unique per-session identifier (`socket.handshakeHash`) for crypto binding
*Secure vs Insecure Mode:*
- `hs://s000...` = *Secure* (prefix `s`) - Full Noise handshake with authentication - `hs://0000...` = *Insecure* - Presumably skips authentication (anonymous connections)
*The flow:*
``` 1. Peer A generates keypair → announces publicKey to DHT 2. Peer B looks up publicKey → initiates holepunch 3. After UDP connection established: a. Noise XX handshake begins (ephemeral keys exchanged) b. Both sides derive shared secret c. secretstream initialized with derived keys 4. All subsequent data encrypted with XChaCha20-Poly1305 ```
-----
### Key Properties
- *Identity-based routing*: Peers connect by public key, not IP address - works even if you move networks - *E2E encrypted by default*: No way for DHT nodes or relays to read your traffic - *No central servers*: Bootstrap nodes exist but only for DHT entry; traffic never routes through them - *Firewall support*: Optional `firewall()` callback to accept/reject connections by remotePublicKey
-----
### References
- Holesail: <https://github.com/holesail/holesail> - HyperDHT: <https://github.com/holepunchto/hyperdht> - Hyperswarm Secret Stream: <https://github.com/holepunchto/hyperswarm-secret-stream> - Holepunch docs: <https://docs.holepunch.to/building-blocks/hyperswarm> - Hypertele (predecessor): <https://github.com/bitfinexcom/hypertele>
supersuryaansh•2mo ago
If you have a particular question about it, I am happy to help.