Hyperlink: A Tool for High-Speed Peer-to-Peer Transfers
Primary Purpose:
Hyperlink is a C++ command-line interface (CLI) and library designed to facilitate high-speed peer-to-peer file transfers, benchmarking, and auto-discovery over USB4 and Thunderbolt network links exposed by the operating system.
Key Features:
High-Speed Transfers: Enables efficient data sharing between computers using USB4 or Thunderbolt connections.
File Transfer CLI: Offers a user-friendly tool for sending and receiving files directly over supported networks.
Auto-Discovery Mechanism: Automatically detects peers on the network, simplifying setup and reducing manual configuration.
Cross-Platform Support: Works seamlessly across multiple operating systems, including macOS, Linux, and Windows, ensuring broad compatibility.
Benchmarking Tools: Provides utilities to measure and optimize network performance for high-speed links.
Audience & Benefits:
Ideal for developers, system administrators, and professionals who require fast and reliable file transfers. Hyperlink offers efficient file sharing, automated network discovery, and precise performance measurement, making it a valuable tool for optimizing data transfer operations over USB4 or Thunderbolt connections.
Hyperlink can be installed on Windows via winget, ensuring easy setup and integration into existing workflows.
README
Hyperlink
Hyperlink is a C++20 library skeleton for high-speed peer-to-peer data transfer between computers over a USB link, with automatic peer discovery and connection configuration.
If libusb is not installed, the project still builds and tests the portable library layer. The USB probing example will print that USB support is disabled.
Project Layout
include/hyperlink/ public headers
src/ library implementation and transport backends
The long-term goal is to use the fastest transport exposed by the connected hardware, including USB4-class links when the OS and cable/device path make that available.
Important constraints:
A USB4 port is not automatically a raw peer-to-peer data pipe between two computers.
Generic libusb code can work well for USB devices with bulk endpoints, but it normally sees USB device speeds exposed by the operating system, not raw USB4 fabric bandwidth.
Reaching USB4 20Gbps, 40Gbps, or 80Gbps class throughput may require a USB4/Thunderbolt networking interface, PCIe tunneling, a certified bridge device, or a custom device-mode/gadget endpoint depending on platform.
Hyperlink should negotiate the best available link and report the detected/theoretical speed, then benchmark real application throughput separately.
USB4/Thunderbolt Network Benchmark
When the OS exposes a USB4 or Thunderbolt connection as a network interface, use the TCP benchmark transport to measure the real application-level throughput.
Easy mode:
# receiver
hyperlink test receive
# sender, use the receiver's USB4/Thunderbolt 169.254.x.x address
hyperlink test send
--parallel 8 uses ports 47777 through 47784, so allow that range through the firewall if needed.
Helpful commands for finding the right interface:
# macOS
ifconfig
networksetup -listallhardwareports
# Linux
ip addr
ip route
# Windows PowerShell
Get-NetAdapter
Get-NetIPAddress
The benchmark uses TCP intentionally. That lets the operating system select the high-speed USB4/Thunderbolt network interface when the peer IP belongs to that link, while the same code remains portable across macOS, Linux, and Windows.
Deploy Server Over The USB4/Thunderbolt Link
From the MacBook, you can push the current source to the Mac mini over the USB4/Thunderbolt network IP, rebuild it there, and start the benchmark server:
scripts/deploy_server.sh --host 169.254.119.3 --user user
That command uses SSH and rsync. On the Mac mini, enable System Settings > General > Sharing > Remote Login first, then check that SSH works:
ssh user@169.254.119.3
The deploy script defaults to:
remote directory: ~/Hyperlink
CMake preset: release
server ports: 47777..47784
parallel streams: 8
socket buffer: 8388608
After deployment, run the client from the MacBook:
Use hyperlink for one-shot file transfer over the same USB4/Thunderbolt network path.
On the receiving computer:
hyperlink receive
Receivers answer discovery requests on UDP port 47789 by default and provide a TCP
throughput probe. The responder moves a requested probe port out of its transfer stream
range; the default 47790 receiver with eight streams therefore advertises probe port
47798. On the sending computer, let Hyperlink discover local receivers, measure each
responder's TCP probe throughput, and use the fastest peer's transfer settings:
hyperlink send /path/to/file-or-directory
Auto-discovery broadcasts on every local IPv4 subnet, including USB, Wi-Fi, Ethernet,
and loopback interfaces. It ranks valid responders by measured TCP probe throughput;
there is no address-class preference.
You can still target a known address manually:
hyperlink send /path/to/file-or-directory --host
Use hyperlink receive --out to choose the output directory. Use --no-advertise
on the receiver to disable discovery. Use --discovery-port on both sides if
47789 is already in use.
The receiver saves only the base filename for single files, so paths from the sender are
not recreated on the receiving machine.
Directories and .app bundles can be sent directly:
hyperlink send /Applications/MATLAB_R2026a.app
The friendly CLI defaults to --parallel 8. The equivalent advanced commands are:
With parallel directory transfer, Hyperlink uses its native directory mode instead of tar.
It transfers files across multiple sockets, recreates directories, preserves regular file
permissions, and recreates symlinks. It can still be limited by many small filesystem
writes, but it avoids the slow pre-tar step.
Windows Laptop Receiver
Install MSYS2 from , then open MSYS2 UCRT64 and install the build tools:
Windows may block symlink creation unless Developer Mode or elevated permissions are enabled. If symlink creation fails, Hyperlink writes a small *.hyperlink-symlink.txt file containing the symlink target instead of failing the whole transfer.
Publishing Releases
Run the Release native packages workflow from the GitHub Actions tab and enter a tag
such as v0.1.7. You can also publish by pushing a version tag:
git tag v0.1.7
git push HyperLink v0.1.7
The Release native packages workflow attaches native archives to the GitHub Release.
The archives are named by OS and CPU, for example:
The Publish APT repository workflow publishes the .deb release asset as a minimal
APT repository on GitHub Pages. It runs automatically after a GitHub Release and can
also be started manually for a release tag.
The Homebrew formula lives in the public tap repo and is updated for each release:
https://github.com/Chaoos-404/homebrew-hyperlink
WinGet manifests are kept under packaging/winget/. The current release manifest is
0.1.7. Submit that directory to microsoft/winget-pkgs to make
winget install Chaoos404.Hyperlink available publicly after Microsoft accepts the PR.
Current Milestones
Define the public session, transport, and auto-configuration API.
Build a libusb discovery backend for compatible USB data-transfer devices.
Add the wire protocol handshake for role selection, packet sizing, encryption preference, and endpoint capabilities.
Add throughput and latency benchmarks using loopback/fake transport first, then real USB hardware.
Add OS-specific high-speed transports where useful, such as Thunderbolt/USB4 networking or PCIe-tunneled devices.
Notes
Normal USB cables do not make two computers peers by themselves; one side normally acts as host and the other as device. For computer-to-computer transfer, plan around a USB bridge/data-transfer cable, a USB gadget/device-capable board, or another link that exposes bulk endpoints the library can claim.
The public API is intentionally platform-neutral. OS-specific work should stay behind Transport implementations so the session and auto-configuration layers remain portable.