Table of Contents
BeamSync is a cross-platform, desktop file transfer application engineered for speed and reliability. Built with Go (Wails v2) and Svelte, it establishes direct, high-bandwidth connections over your local area network — no internet required, no cloud involved, no accounts needed. Files go straight from one device to another.
- ⚡ High-Speed Local Transfer — Streams files directly over HTTP on your LAN for maximum throughput.
- 🔒 Fully Offline — Works without internet access. Data never leaves your local network.
- 📱 Cross-Device via QR Code — Connect any mobile device instantly by scanning a QR code — no app install required on the phone.
- 📂 Drag & Drop — Drop files onto the window to begin transfer immediately.
- 🧠 Smart Networking —
- Auto-detects the optimal local IP address.
- Finds open ports automatically to avoid conflicts.
- Configures firewall rules on Linux when needed.
- 🔊 Auditory Feedback — Integrated audio engine provides real-time interaction sounds.
- ♿ Accessible — Respects
prefers-reduced-motionfor all animations.
The project is structured as a Go workspace with two modules:
BeamSync/
├── beamsync/ # Core library (Go module)
│ ├── server.go # StartServer(), StartSender() — HTTP file streams
│ ├── port_manager.go# FindAvailablePort() — dynamic port binding
│ ├── firewall.go # RunFirewallSetup() — Linux firewall automation
│ └── ...
├── desktop/ # Wails desktop application (Go + Svelte)
│ ├── app.go # App lifecycle, config, event bridge
│ ├── frontend/ # Svelte + Vite UI
│ └── ...
└── go.work # Go workspace root
| Layer | Technology | Key Components |
|---|---|---|
| Frontend | Svelte + Vite | Reactive UI, drag-and-drop, QR display |
| Application Shell | Go + Wails v2 | App — event loop, config persistence (loadConfig, saveConfig) |
| Network Engine | Go (net/http) | StartServer, StartSender, writeFileToDisk — concurrent file I/O |
| Utilities | Go | getLocalIP, FindAvailablePort, RunFirewallSetup |
| Media | Go | AudioEngine — native audio playback |
Architecture details derived from graphify analysis: 172 nodes, 223 edges, 20 communities.
yay -S beamsync-binDownload the latest release from the Releases page.
-
Clone the repository:
git clone https://github.com/PranavAgarkar07/BeamSync.git cd BeamSync -
Install frontend dependencies:
cd desktop/frontend && npm install && cd ../..
-
Run in development mode (hot reload):
cd desktop && wails dev
-
Build for production:
cd desktop && wails build
Compiled binaries are output to
desktop/build/bin/.
- Launch BeamSync.
- A connection QR code and URL are displayed automatically.
- Scan the QR code from a mobile device, or open the URL from another machine on the network.
- Incoming files are saved to
Downloads/BeamSync/.
- Click Send or drag files onto the window.
- Select the files to transfer.
- A unique URL and QR code are generated.
- Open the URL or scan the QR on the receiving device to start the download.
BeamSync works by starting a local HTTP server that other devices on your LAN connect to (via browser or curl). In some network environments, the connection may not work as expected.
- All devices must be connected to the same local network / subnet. Devices on different VLANs or isolated network segments may not be able to reach each other.
- Both devices must be able to communicate over LAN (HTTP reachability, not automatic discovery)
- macOS (14+ Sonoma/Sequoia): Grant Local Network permission — go to System Settings → Privacy & Security → Local Network → enable BeamSync. The app will prompt on first launch.
- Mobile hotspots: Some enforce client isolation; tethered devices may not reach the host
The following network types may block or limit BeamSync functionality:
- Guest WiFi networks often isolate devices from each other
- Public WiFi networks (cafes, airports, hotels) often restrict device-to-device traffic
- Enterprise, office, or school networks may use client isolation or VLAN segmentation that prevents devices from reaching each other
- Routers with AP isolation / client isolation enabled block all LAN device communication
- NAT hairpinning: On single-router home networks, some routers cannot route traffic back to a device on the same LAN when using the external IP or hostname. Use the local IP (e.g.
192.168.x.x) directly. - Third-party antivirus software (Norton, McAfee, Kaspersky, etc.) may silently block LAN HTTP servers. Temporarily disable or add an exclusion for BeamSync.
- Firewalls on Linux, Windows, or macOS may block incoming connections
- BeamSync uses TCP ports 3000–3098 for local transfers. Ensure these ports are allowed through your firewall when necessary.
- On Linux, BeamSync can automatically configure firewall rules when required through its built-in firewall setup mechanism (
ufw,firewalld, oriptables). - Ensure BeamSync is allowed through your system firewall if prompted
If devices cannot connect, try these diagnostics:
# Check basic network reachability
ping <receiver-ip>
# Verify BeamSync's HTTP server is responding
curl -v http://<receiver-ip>:<port>/
# Check if the port is listening (from the receiver)
netstat -an | grep <port>
# Confirm both devices are on the same subnet
ip addr show | grep "inet "
Quick steps:
- Confirm both devices are on the same WiFi network
- Disable VPNs or proxies temporarily
- Try connecting via the device's local IP address instead of hostname
- Test with a mobile hotspot or a different home network
- Temporarily disable third-party antivirus to isolate the cause
For developers, contributors, and security auditors who want to understand the underlying peer-to-peer file transfer protocol or build custom scripts/clients, the complete HTTP API and authentication specifications are available in the API Documentation (API.md).
- Local-only — All transfers happen over your LAN. No external servers are contacted.
- Optional HTTPS — Set
BEAMSYNC_ENABLE_TLS=truebefore launching BeamSync to serve receiver and sender pages over HTTPS with a persisted ECDSA local certificate in~/.config/beamsync/. - Zero data collection — BeamSync does not store, transmit, or analyze your files beyond the direct LAN transfer.
- Open source — The entire codebase is available for audit.
This project is licensed under the MIT License. See the LICENSE file for details.
Contributions are welcome. Please open an issue or submit a pull request.