polius/FileSync: Self-Hosted P2P File Sharing for Developers

polius/FileSync: Self-Hosted P2P File Sharing for Developers

Transferring files between devices shouldn't require uploading to third-party clouds, managing accounts, or hitting arbitrary size limits. Yet most developers still resort to proprietary services or complex SFTP setups when they need to move data quickly. polius/FileSync offers a different path: a self-hosted, peer-to-peer solution that runs entirely in the browser, supports real-time one-to-many distribution, and handles multi-gigabyte files without exhausting system memory.

This guide examines what polius/FileSync does, how it works under the hood, and how to deploy it yourself. All technical claims below derive directly from the project's README and repository metadata—no extrapolated benchmarks or invented adoption metrics.

What is polius/FileSync?

polius/FileSync is an open-source file transfer tool maintained by GitHub user polius. The project—released under the MIT License and built primarily in JavaScript^{↗ Bright Coding Blog}—has accumulated 1,315 stars and 122 forks as of its last commit on July 16, 2026. It occupies a specific niche in the developer tooling landscape: browser-based, WebRTC-powered peer-to-peer file sharing with a self-hosting emphasis.

The tool's core proposition is straightforward but technically distinctive. Rather than routing files through an intermediary server, polius/FileSync establishes direct encrypted connections between browsers using WebRTC. A lightweight signaling server assists only with initial handshake—exchanging SDP offers, answers, and ICE candidates—then steps out of the data path entirely. This architecture means the server never possesses file contents, addressing a persistent concern with cloud-based transfer services.

The relevance of this approach has grown alongside increasing scrutiny of data residency, vendor lock-in, and the operational complexity of maintaining secure file infrastructure. For development teams, DevOps^{↗ Bright Coding Blog} engineers, and security-conscious organizations, polius/FileSync represents a middle ground between consumer cloud tools and heavy enterprise file transfer protocols.

Notably, the project emphasizes operational simplicity: a single Docker^{↗ Bright Coding Blog} image, no recipient account requirements, and automatic NAT traversal with STUN/TURN fallback. These design choices reflect an understanding that developer tools succeed when they reduce friction without sacrificing control.

Key Features

Private by design with encrypted WebRTC. File transfers occur directly between browsers over encrypted channels. The server brokers only the initial connection setup, making it architecturally incapable of accessing file contents. This property holds regardless of deployment scale or user count.

No practical file size limit. Received files stream directly to disk rather than buffering in memory. The README explicitly notes that "even multi-gigabyte transfers use almost no memory" when operating over HTTPS. This streaming capability distinguishes polius/FileSync from browser-based tools that rely on in-memory Blob storage.

One-to-many distribution model. A single sender can distribute to unlimited recipients simultaneously by sharing a room link or QR code. This broadcast pattern suits scenarios like distributing build artifacts, sharing datasets with research collaborators, or pushing configuration files across a device fleet.

Cross-network connectivity with automatic fallback. Direct peer connections form when network conditions permit. For restrictive NATs, symmetric NATs, or UDP-blocking firewalls, the system automatically falls back to STUN/TURN relay through the configured coturn server. The README estimates this affects approximately 5–10% of connections.

Zero-install recipient experience. Recipients open a link in any modern browser—no application installation, no account creation. Optional per-room password protection adds an access control layer without complicating the core workflow.

Containerized self-hosting. The entire system deploys as a single Docker image with documented Compose configurations for both HTTP (local/trusted network) and HTTPS (public domain) scenarios.

Use Cases

Development team artifact distribution. When a build pipeline produces large binaries, container images, or test datasets, polius/FileSync enables immediate distribution to QA devices, staging servers, or remote team members without consuming CI/CD storage quotas or exposing proprietary artifacts to third-party services.

Cross-platform media and dataset sharing. ML practitioners frequently need to move training datasets, model checkpoints, or evaluation outputs between workstations, cloud instances, and edge devices. The streaming-to-disk architecture prevents memory exhaustion with multi-gigabyte files that would crash conventional browser-based transfers.

Air-gapped or privacy-sensitive environments. Organizations with strict data residency requirements—healthcare, finance, defense contractors—can deploy polius/FileSync internally without external service dependencies. The self-hosted model and encrypted P2P architecture satisfy compliance frameworks that prohibit third-party data processing.

Ad-hoc collaboration without infrastructure overhead. Freelancers, open-source maintainers, and small teams can spin up a FileSync instance for specific projects or events, then decommission it. The Docker-based deployment avoids the ongoing operational burden of maintaining dedicated file servers or VPN infrastructure.

Educational and workshop settings. Instructors sharing large datasets, virtual machine images, or code repositories with students can generate a room link and QR code, eliminating the bandwidth bottleneck of centralized distribution and reducing support overhead from students struggling with alternative transfer methods.

Installation & Setup

polius/FileSync requires Docker, Docker Compose, and Python^{↗ Bright Coding Blog} 3 (for initial secret generation). Every deployment needs a secret key that signs TURN credentials for NAT traversal.

Generate the Secret Key

python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"

⚠️ Use your own generated value—never deploy with example placeholders.

Option A: HTTP (Local Network / Quick Start)

Best for evaluation or trusted LAN environments. The README warns that large transfers exceeding ~500 MB are unreliable over plain HTTP due to browser Blob limitations.

1. Download the compose file:

curl -O https://raw.githubusercontent.com/polius/FileSync/main/deploy/docker-compose.yml

2. Edit both <SECRET_KEY> placeholders with your generated value:

# deploy/docker-compose.yml (excerpt)
services:
  filesync:
    # ...
    environment:
      - SECRET_KEY=Hs9k…your-generated-key…=
  coturn:
    # ...
    command:
      - --static-auth-secret=Hs9k…your-generated-key…=

3. Start the services:

docker compose up -d

Access at http://localhost or your server's IP address.

Option B: HTTPS (Public Domain, Recommended)

Enables memory-safe streaming for files of any size. Caddy handles Let's Encrypt certificate provisioning automatically.

1. Download required files:

curl -O https://raw.githubusercontent.com/polius/FileSync/main/deploy/docker-compose-ssl.yml
curl -O https://raw.githubusercontent.com/polius/FileSync/main/deploy/Caddyfile

2. Set your secret in docker-compose-ssl.yml (same replacement as Option A).

3. Configure your domain in Caddyfile:

# deploy/Caddyfile
filesync.example.com {
    reverse_proxy filesync:80
}

4. Deploy:

docker compose -f docker-compose-ssl.yml up -d

Access at https://yourdomain.com.

Stop FileSync

docker compose down                          # HTTP setup
docker compose -f docker-compose-ssl.yml down  # HTTPS setup

Real Code Examples

The polius/FileSync README provides configuration examples rather than application code, reflecting its nature as a deployed service rather than a library. Below are the documented configuration patterns with explanatory context.

Docker Compose HTTP Configuration

# deploy/docker-compose.yml — simplified illustrative excerpt
services:
  filesync:
    image: poliuscorp/filesync:latest
    ports:
      - "80:80"    # Host port 80 maps to container port 80
    environment:
      - SECRET_KEY=<SECRET_KEY>  # Replace with generated value
    # ... additional service configuration
  
  coturn:
    image: coturn/coturn:latest
    # ...
    command:
      - --static-auth-secret=<SECRET_KEY>  # Must match SECRET_KEY above
      - --realm=filesync
      - --listening-port=3478

This configuration establishes the two-container architecture: the FileSync application server and the coturn TURN server for relay fallback. The SECRET_KEY and --static-auth-secret must match—this shared secret enables cryptographically signed TURN credentials that prevent unauthorized relay usage. The port mapping 80:80 exposes the web interface on standard HTTP.

Custom HTTP Port Configuration

# Modified docker-compose.yml for non-standard host port
services:
  filesync:
    image: poliuscorp/filesync:latest
    ports:
      - "8080:80"   # serve on http://localhost:8080
    environment:
      - SECRET_KEY=Hs9k…your-generated-key…=

The README emphasizes that the first number in the port mapping is the host-accessible port, while the second must remain 80 as the internal container port. This pattern allows multiple FileSync instances or cohabitation with existing services on port 80.

Caddyfile for HTTPS Deployment

# deploy/Caddyfile — domain configuration
filesync.example.com {
    reverse_proxy filesync:80
}

Caddy's automatic HTTPS provisions and renews certificates without manual intervention. The reverse_proxy directive forwards all traffic to the FileSync container's internal HTTP port. For non-standard external HTTPS ports, the README recommends placing an additional reverse proxy (Nginx, Traefik, or standalone Caddy) in front, terminating TLS there and forwarding to FileSync's internal port.

TURN Relay Port Range

# Excerpt showing UDP relay range in compose configuration
services:
  coturn:
    # ...
    ports:
      - "3478:3478/tcp"
      - "3478:3478/udp"
      - "50000-50100:50000-50100/udp"

The 50000–50100 UDP range carries relayed traffic for connections that cannot establish direct peer-to-peer paths. The README notes this affects roughly 5–10% of connections, typically peers behind symmetric NAT or UDP-blocking firewalls.

Advanced Usage & Best Practices

Always deploy HTTPS for production use. The README is explicit: HTTPS (or localhost) is required for the File System Access API and Service Worker streaming methods. Without these, transfers fall back to in-memory Blob storage, which becomes unreliable beyond ~500 MB and exhausts browser memory with larger files.

Generate and protect your secret key properly. The SECRET_KEY is a cryptographic root of trust for TURN relay access. Rotate it periodically, store it in a secrets manager rather than version control, and ensure the coturn --static-auth-secret remains synchronized with the FileSync SECRET_KEY environment variable.

Monitor TURN relay utilization. The 5–10% fallback rate to relayed connections means the UDP port range 50000–50100 sees proportionally less traffic, but plan capacity for your peak concurrent user count. Each relayed connection consumes one port in this range for the transfer duration.

Consider network topology for firewall rules. The required ports—80/443 for web, 3478 TCP/UDP for STUN/TURN signaling, and 50000–50100 UDP for relay—must be accessible from all potential peer networks, not just the server itself. Corporate firewalls often block the high UDP range; document this for users in restricted environments.

Use room passwords for sensitive transfers. While the P2P architecture prevents server access to contents, the room link itself is an unauthenticated access vector until password protection is enabled. Enable this before sharing links for confidential material.

Comparison with Alternatives

Magic Wormhole offers comparable privacy guarantees through PAKE-encrypted relay, but requires command-line installation for all participants—friction that polius/FileSync eliminates with its browser-only recipient experience. Conversely, Wormhole's relay model works reliably in all network conditions without TURN server configuration complexity.

Snapdrop shares the browser-based P2P approach but lacks polius/FileSync's streaming-to-disk architecture, limiting practical transfer sizes by browser memory. Its network discovery also typically requires same-LAN proximity, whereas polius/FileSync's TURN fallback enables cross-network transfers.

The discontinued Firefox Send illustrates the risk of centralized services: useful tools vanish when business priorities shift. polius/FileSync's self-hosted model insulates users from this dependency.

FAQ

Does polius/FileSync require accounts or registration? No. Senders and recipients use room links without any account creation. Optional per-room passwords provide access control.

What file sizes can it handle? No hard limit. Multi-gigabyte transfers stream to disk over HTTPS with near-zero memory usage. HTTP deployments fall back to Blob storage and become unreliable past ~500 MB.

Can recipients use mobile browsers? Yes, any modern browser supporting WebRTC. The File System Access API (for optimal streaming) requires desktop Chromium browsers over HTTPS.

Is the server ever exposed to file contents? No. The signaling server handles only connection setup; encrypted data flows directly between peer browsers via WebRTC.

What license applies? MIT License, permitting commercial and private use with attribution.

How active is development? Last commit dated July 16, 2026 per repository metadata. Evaluate recency against your stability requirements.

Can I run this behind an existing reverse proxy? Yes. Terminate TLS at Nginx, Traefik, or Caddy and forward to FileSync's internal HTTP port. The README documents this pattern for non-standard port deployments.

Conclusion

polius/FileSync addresses a genuine gap in developer tooling: private, large-scale file distribution without third-party dependency or recipient friction. Its WebRTC architecture, streaming-to-disk implementation, and containerized deployment make it particularly suitable for teams prioritizing data sovereignty, working with large artifacts, or supporting recipients who cannot install specialized software.

The tool is best suited for: development and DevOps teams needing ad-hoc file distribution; organizations with compliance requirements prohibiting cloud file services; and educators or event organizers requiring immediate, multi-recipient sharing. It is less optimal for users needing guaranteed delivery without any server infrastructure, or those requiring persistent file storage rather than real-time transfer.

With 1,315 stars and active maintenance through mid-2026, polius/FileSync has demonstrated sufficient community traction to evaluate for production use. Deploy the Docker compose configuration, test with your typical file sizes and network conditions, and verify TURN fallback behavior in your specific environment.

Explore the repository, review the full documentation, and download the latest release at https://github.com/polius/FileSync.