scorpiox-thunderbolt4 Networking
Raw Ethernet file transfer over Thunderbolt 4. Bypasses TCP/IP entirely — BPF-based, MAC-only addressing, jumbo frames.
Overview
scorpiox-thunderbolt4 is a raw Ethernet file transfer tool built for Thunderbolt 4 bridges. It bypasses the entire TCP/IP stack, sending data as raw Ethernet frames using BPF (Berkeley Packet Filter). Addressing is done purely via MAC addresses — no IP, no ports, no sockets. With jumbo MTU support (9000 bytes), it achieves near-wire-speed transfers between two macOS machines connected via Thunderbolt 4 cable.
Raw Ethernet I/O
Sends data as raw Ethernet frames using EtherType 0x88B5 (IEEE 802.1 experimental). No IP headers, no TCP handshakes, no overhead.
BPF-Based Frame I/O
Uses Berkeley Packet Filter for direct frame injection and capture on macOS. Reads and writes raw frames through /dev/bpf devices.
Auto-Detect Interface
Automatically discovers the Thunderbolt bridge network interface (bridge* on macOS) — no manual interface configuration needed.
Jumbo MTU (9000)
Configures the Thunderbolt bridge interface for 9000-byte jumbo frames, maximizing payload per frame and minimizing overhead.
MAC-Only Addressing
No IP addresses required. Sender and receiver are identified solely by their MAC addresses on the Thunderbolt bridge.
Pure C, Zero Deps
Written in pure C with no external dependencies. Source: scorpiox-thunderbolt4.c + libtb4/tb4_transport.c — compiles to a tiny static binary.
Wire Protocol
scorpiox-thunderbolt4 operates at Layer 2, using raw Ethernet frames with a custom EtherType.
┌──────────────────────────────────────────────────────────────┐
│ Raw Ethernet Frame │
├──────────┬──────────┬──────────┬─────────────────────────────┤
│ Dst MAC │ Src MAC │ EtherType│ Payload │
│ 6 bytes │ 6 bytes │ 0x88B5 │ up to 8958 bytes │
│ │ │ 2 bytes │ (jumbo MTU 9000 - 42) │
└──────────┴──────────┴──────────┴─────────────────────────────┘
│
▼
IEEE 802.1 Local Experimental EtherType
No IP header · No TCP/UDP · No ports
IEEE reserves 0x88B5–0x88B6 for local experimental use. These frames are never routed by switches or forwarded beyond the local link — perfect for a point-to-point Thunderbolt cable connection.
// Open BPF device for raw frame access int fd = open("/dev/bpf0", O_RDWR); // Bind to Thunderbolt bridge interface struct ifreq ifr; strlcpy(ifr.ifr_name, "bridge0", IFNAMSIZ); ioctl(fd, BIOCSETIF, &ifr); // Set BPF filter: only accept EtherType 0x88B5 struct bpf_program filter; // BPF bytecode: ldh [12], jeq #0x88B5, ret #-1, ret #0 ioctl(fd, BIOCSETF, &filter); // Enable immediate mode for low-latency reads int enable = 1; ioctl(fd, BIOCIMMEDIATE, &enable);
How It Works
A direct point-to-point transfer between two macOS machines connected via Thunderbolt 4 cable.
Connect Hardware
Connect two Macs with a Thunderbolt 4 / USB4 cable. macOS automatically creates a bridge interface (typically bridge0) with IP-less link-local connectivity.
Auto-Detect Interface
scorpiox-thunderbolt4 scans network interfaces, identifies the Thunderbolt bridge by type, reads its MAC address, and configures jumbo MTU (9000 bytes).
Open BPF Device
Opens /dev/bpf*, binds to the bridge interface, and installs a BPF filter that only accepts frames with EtherType 0x88B5. Enables immediate mode for low-latency I/O.
Send / Receive Frames
The sender fragments the file into jumbo-sized Ethernet frames and writes them via BPF. The receiver captures matching frames, reassembles the payload, and writes to disk.
Verify & Complete
Transfer integrity is verified at the frame level. The receiver confirms completion and reports throughput statistics.
Usage Examples
Run as root on both machines. One listens, the other sends.
# Start listening for incoming thunderbolt4 transfer $ sudo scorpiox-thunderbolt4 receive scorpiox-thunderbolt4: detected bridge interface bridge0 scorpiox-thunderbolt4: MAC a4:83:e7:2b:11:f0 scorpiox-thunderbolt4: MTU set to 9000 scorpiox-thunderbolt4: BPF filter installed (EtherType 0x88B5) scorpiox-thunderbolt4: waiting for frames...
# Send a file to the receiver's MAC address $ sudo scorpiox-thunderbolt4 send a4:83:e7:2b:11:f0 ./project-backup.tar.gz scorpiox-thunderbolt4: detected bridge interface bridge0 scorpiox-thunderbolt4: MAC a4:83:e7:4c:22:a1 scorpiox-thunderbolt4: MTU set to 9000 scorpiox-thunderbolt4: sending project-backup.tar.gz (4.7 GB) scorpiox-thunderbolt4: target MAC a4:83:e7:2b:11:f0 [████████████████████████████████████] 100% 4.7 GB ~3.2 GB/s scorpiox-thunderbolt4: transfer complete — OK
# Usage scorpiox-thunderbolt4 send <dst-mac> <file> # send file to MAC scorpiox-thunderbolt4 receive # listen for incoming scorpiox-thunderbolt4 detect # show bridge interface info # Auto-detect example $ sudo scorpiox-thunderbolt4 detect interface: bridge0 mac: a4:83:e7:2b:11:f0 mtu: 9000 type: Thunderbolt Bridge status: active
BPF device access and raw Ethernet frame injection require root privileges on macOS. The tool will exit with a clear error if run unprivileged.
Requirements
Hardware and software prerequisites for using scorpiox-thunderbolt4.
Comparison
How scorpiox-thunderbolt4 compares to other file transfer methods between Macs.
| Feature | thunderbolt4 | scorpiox-beam | AirDrop | scp | Target Disk |
|---|---|---|---|---|---|
| Protocol Layer | Layer 2 (Ethernet) | Layer 4 (TCP) | Layer 7 (AWDL) | Layer 7 (SSH) | Block device |
| TCP/IP Stack | Bypassed entirely | Required | Required | Required | N/A |
| Throughput | ~3+ GB/s | ~1 GB/s | ~15 MB/s | ~100 MB/s | ~3 GB/s |
| Encryption | None (link-local) | None | TLS | SSH | None |
| Configuration | Zero config | Zero config | Bluetooth pairing | SSH keys | Reboot to TDM |
| Dependencies | None (pure C) | None (pure C) | macOS built-in | OpenSSH | macOS built-in |
| Cross-platform | macOS only | Linux/macOS/Win | Apple only | All | Mac only |
| Requires Cable | TB4 / USB4 | Network | Wireless | Network | TB cable |
Network Stack
scorpiox-thunderbolt4 is one of 15 pure C networking components in the scorpiox stack — covering DNS, tunneling, proxying, transfer, email, and more.