logo
logo

PeerBeam CLI

GitHub

Overview

Peerbeam CLI is a command-line tool for fast, secure, and efficient peer-to-peer file transfers. Unlike conventional methods that rely on intermediary hosting services or relay servers to store and forward data, Peerbeam uses WebRTC through the Pion library to create a direct connection between devices.

Technologies

  • Programming Language: Go
  • Deployment: Self-contained binary (available via Homebrew and go install)
  • Connection Protocol: WebRTC
  • WebRTC Library: Pion

The Problem

Most existing solutions for file transfers fall into two categories. On one hand, there’s FTP/SFTP, which are fast and reliable but not always practical. It requires network configuration and a server on the receiving side, which doesn't really work for mobile users. On the other hand, you might turn to file-hosting services or email attachments, both of which introduce upload/download delays.
WebRTC addresses these issues by bypassing intermediaries entirely, transferring data directly between devices.

How it works

  1. Session Initialization: The sender and receiver initialize the tool, generating session identifiers through a public STUN server.
  2. Connection Setup: Users exchange encoded session descriptor information. Then the Pion library handles session negotiation, including NAT traversal.
  3. File Transfer: After the connection is established, files are streamed directly between devices using WebRTC’s DataChannels, ensuring high performance.

Unlike Peerbeam Web, the CLI app operates without the limitations imposed by the browser environment, so it can achieve much higher transfer speeds.

Challenges

WebRTC handles NAT traversal well in most cases, but when two users are both trying to connect from behind symmetric NATs, a direct connection isn’t possible. These networks tightly control how external addresses are mapped, making it necessary to use a TURN server to relay data between devices. While this means relying on a third-party server, the data remains encrypted. The relay acts as a communication layer between the two computers, enabling simultaneous uploading and downloading. This makes transfers faster than traditional file hosting, where files are first uploaded and then downloaded sequentially.

Future Plans

  • Host a TURN server to serve as a fallback for both the web and CLI apps.
  • Improve directory transfer functionality between different operating systems.
  • Add support for customizing compression settings/type, proxies, and using your own relay server.