scorpiox-beam
Zero-copy file transfer over TCP. No config, no dependencies — just send and receive on port 9876.
Overview
scorpiox-beam is a single-purpose file transfer tool built in pure C.
It moves files between machines on a LAN using a custom binary protocol
over TCP port 9876. The sender reads a file and pushes it through the
kernel's zero-copy path — sendfile() on Linux, sendfile()
on macOS, or TransmitFile() on Windows — so the file data never
touches userspace. The receiver writes the incoming stream to disk and
verifies integrity with an xxHash64 checksum. No configuration files, no
dependencies, no TLS negotiation. One binary, two commands.
Features
Built for speed on trusted networks.
Zero-Copy Transfer
Uses OS-level zero-copy syscalls to move file data directly from disk to socket, bypassing userspace buffers entirely.
Cross-Platform
Linux sendfile(), macOS sendfile(), Windows TransmitFile(). Same protocol, same binary format, any OS.
xxHash64 Checksum
Every transfer is verified with xxHash64 — a non-cryptographic hash that runs at memory bandwidth speeds.
Binary Header Protocol
Fixed-size binary header carries filename, file size, and checksum. No JSON parsing, no text protocols, no overhead.
ACK/NAK Confirmation
Receiver sends a 1-byte ACK on checksum match or NAK on mismatch. Both sides know the transfer result before closing.
Progress Display
Real-time transfer progress with speed calculation. See exactly how fast your files are moving across the wire.
Wire Protocol
Custom binary protocol — minimal overhead, maximum throughput.
Header Structure
┌──────────────────────────────────────────────────────────┐
│ BEAM HEADER (fixed size) │
├──────────┬──────────┬───────────────┬────────────────────┤
│ magic │ filesize │ xxhash64 │ filename │
│ 4 bytes │ 8 bytes │ 8 bytes │ 256 bytes │
│ "BEAM" │ uint64 │ uint64 │ null-terminated │
├──────────┴──────────┴───────────────┴────────────────────┤
│ FILE DATA (raw bytes) │
│ ... filesize bytes ... │
├──────────────────────────────────────────────────────────┤
│ ACK / NAK (1 byte) │
│ 0x06 = ACK, 0x15 = NAK │
└──────────────────────────────────────────────────────────┘
typedef struct { char magic[4]; // "BEAM" uint64_t filesize; // file size in bytes uint64_t checksum; // xxHash64 of file data char filename[256]; // null-terminated filename } beam_header_t;
How It Works
Four steps. No handshake negotiation, no capability exchange.
Receiver Listens
The receiver binds to TCP port 9876 and waits for a single connection. One transfer per invocation — no session management.
Sender Connects
The sender opens a TCP connection to the receiver, computes the xxHash64 checksum of the file, and sends the binary header with filename, size, and hash.
Zero-Copy Transfer
File data is pushed through the kernel's zero-copy path. On Linux, sendfile() splices directly from the file descriptor to the socket. No read() + write() loop, no userspace buffer.
Checksum Verification
The receiver writes data to disk, recomputes xxHash64 over the received file, and compares against the header checksum. Sends ACK (0x06) on match or NAK (0x15) on mismatch.
Zero-Copy Internals
Platform-specific kernel syscalls used for zero-copy I/O.
// Zero-copy: kernel sends file data directly to socket ssize_t sent = sendfile(sock_fd, file_fd, &offset, remaining); // No read() into buffer, no write() from buffer // Data path: disk → page cache → NIC (DMA)
Usage
Two commands. That's it.
Receive a file
# Listen on port 9876, save incoming file to current directory scorpiox-beam receive
Send a file
# Send a file to receiver at 192.168.1.50 scorpiox-beam send 192.168.1.50 ./myfile.tar.gz
Typical output
beam: listening on :9876 beam: connection from 192.168.1.42 beam: receiving myfile.tar.gz (847.3 MB) beam: [████████████████████████] 100% 1.12 GB/s beam: checksum OK (xxh64: a7c3e1f09b2d4e8a) beam: saved to ./myfile.tar.gz
Comparison
How scorpiox-beam compares to common file transfer tools.
| Tool | Zero-Copy | Checksum | Protocol | Dependencies | Setup |
|---|---|---|---|---|---|
| scorpiox-beam | ✓ | xxHash64 | Custom binary | None | 0 config |
| scp | ✗ | HMAC | SSH | OpenSSH | SSH keys |
| rsync | ✗ | MD5/xxHash | rsync/SSH | rsync + SSH | SSH keys |
| netcat | ✗ | ✗ | Raw TCP | nc | Manual pipe |
| croc | ✗ | PAKE | Relay | Go runtime | Code phrase |
Network Stack Context
Where scorpiox-beam fits in the scorpiox network stack.