v0.1.0 — first release
Warning
Superseded by v0.1.1 — do not use this release.
Five transport defects were found in the hyperdht-cpp dependency after this
was published. One is a crash: a double stream-destroy that trips libuv's
assert(!uv__is_closing), and it only bites in Release builds — which is what
the binary below is. The others cause permanent, non-recovering failures: a
write-once relay set that leaves a long-running server unreachable until it is
restarted, no announce-relay failover (-5 forever behind an
endpoint-dependent NAT), a bind-time address snapshot that breaks same-LAN
clients (-6 forever), and a pause()/resume() cycle that leaves the server
permanently silent.
This release is kept published only so the history stays honest.
A C++20 port of holesail 2.4.1 — peer-to-peer TCP/UDP tunnelling over HyperDHT — for hardware where a Node runtime is too heavy.
This is an unofficial, independent port. The protocol, the connection-string scheme and the product are the work of the upstream Holesail project. Use the original unless you specifically need the small footprint; it has features this does not (--filemanager, the desktop and mobile apps, QR pairing) and it is what the Holesail team supports.
Wire-compatible with the original
Same connection strings, key derivation and DHT records. Verified against the real JS 2.4.1 binary on the public DHT — C++↔C++, C++ server ↔ JS client, JS server ↔ C++ client, in both secure and public mode, plus --lookup against a JS-published record. scripts/cross-test.sh is that gate.
The official Holesail phone app connects to a C++ server over mobile data, across carrier NAT.
Footprint
Both idle on the same Raspberry Pi 5, same port, key and mode:
| holesail-cpp | holesail 2.4.1 (Node 24) | ||
|---|---|---|---|
| Resident | 3.2 MB | 77.8 MB | 24× smaller |
Real heap (Pss_Anon) |
0.7 MB | 27.9 MB | 40× smaller |
| Virtual | 3.5 MB | 1.17 GB | |
| Threads | 1 | 7 |
nix build .#holesail-aarch64-static gives a 3.4 MB static binary — scp it onto any aarch64 Linux box, Pi Zero 2 W upward, with zero runtime dependencies.
Scope
--live, --connect, --lookup, TCP and framed UDP, library plus CLI. --help is byte-identical to the JS binary apart from --filemanager.
Not ported: --filemanager, the cli-box output frame, the terminal QR code. Divergences (D1–D5) and reproduced upstream quirks (Q1–Q4) are documented in the README — including one deliberate fix: client --public means public mode, where JS made it mean the opposite of its own --help.
Note for hyperdht-cpp users
Building this surfaced a security bug in hyperdht-cpp: its C-API firewall wrapper inverted its return value, so every private server built on the C FFI admitted exactly the peers it should have refused, and refused the authorised one. Fixed upstream with regression tests. Consumers of the C FFI firewall should update. The C++ API was never affected.
Testing
81 unit cases, 4 network-gated loopback tunnels, clean under ASan and UBSan.
AGPL-3.0-or-later, matching upstream holesail.