Set Up Syncthing: Ultimate Private File Sync Guide

We generate and store more personal data than ever before—photos, code bases, password databases, document archives, and server backups. Relying on commercial cloud providers like Dropbox, Google Drive, or Microsoft OneDrive to sync this data across devices exposes us to subscription paywalls, data harvesting, and service interruptions. If you are serious about data sovereignty, handing your sensitive files to a third party is no longer the best option.

What if you could synchronize your files between your phone, laptop, and home server without paying a monthly fee or uploading your data to corporate datacenters?

Syncthing is an open-source, continuous file synchronization program that works completely peer-to-peer (P2P). Your data travels directly between your devices, encrypted in transit and stored locally on your own hard drives. Having used Syncthing in production environments and for personal file management for years, I consider it an absolute foundational piece of any self-hosted infrastructure.

In this comprehensive guide, we will explore the architecture of Syncthing, cover bare-metal and Docker container installations, configure peer connection trusts, set up file versioning policies, and troubleshoot common networking and file-watching errors to give you an enterprise-grade syncing mesh.

Quick Answer: What is Syncthing?

If you need a fast answer: Syncthing is a decentralized file synchronization application that securely mirrors folders across multiple devices (Windows, macOS, Linux, Android) using direct P2P connections. It replaces commercial cloud storage by allowing your own hardware to securely sync files locally over Wi-Fi or remotely over the internet, completely bypassing centralized third-party servers.

The Core Architecture & Design Philosophy

Syncthing replaces centralized cloud databases with a secure, decentralized synchronization mesh. Instead of a spoke-and-hub model where every device talks to one big server, Syncthing allows every device to talk directly to every other authorized device.

The Block Exchange Protocol (BEP)

Under the hood, Syncthing uses its custom Block Exchange Protocol (BEP) to sync directories efficiently. Here is exactly what happens when you modify a file in a shared folder:

1. File Chunking: When a file is added or changed, Syncthing splits it into variable-sized chunks (typically 128 KiB to 16 MiB, depending on the file size).
2. Hashing: It calculates a SHA-256 cryptographic hash for each block.
3. Metadata Exchange: Devices in your mesh exchange lists of block hashes for each file.
4. Delta Synchronization: Instead of transferring the entire modified file over the network, Syncthing compares the hashes and transmits only the blocks that have changed.

This delta sync behavior saves massive amounts of bandwidth. If you are syncing a 500MB KeepassDX password database or a massive .tar.gz archive generated by BorgBackup, Syncthing will only transfer the few kilobytes that actually changed.

Cryptographic Security & Device Identities

One of the best things about Syncthing is its approach to identity management:

• TLS 1.3 Encryption: All communication between peers is secured using TLS 1.3. Even if you are syncing files over a public airport Wi-Fi network, eavesdroppers cannot intercept your data. This provides robust end-to-end encryption in transit.
• Cryptographic Device IDs: Syncthing does not use traditional usernames or passwords to pair devices. Instead, each device generates a unique 56-character Device ID (a SHA-256 fingerprint of the device’s TLS certificate). Devices must explicitly exchange and approve these IDs before any files can be transferred.
• Untrusted Nodes (Encrypted Folders): Syncthing supports syncing folders to “untrusted” devices. If you rent a cheap VPS from Hetzner Cloud for off-site backups, you can configure Syncthing to encrypt the files locally before transmission. The untrusted VPS will sync the encrypted blocks without ever knowing the filenames or file contents.

Infrastructure Requirements

Before deploying Syncthing, ensure your infrastructure meets the following baseline requirements:

• Hardware: Very lightweight. It can comfortably run on a Raspberry Pi, an old laptop, or a robust Proxmox VE home lab server.
• OS: Compatible with almost any Linux distribution (Ubuntu, Debian, Alpine), Windows, macOS, and Android.
• Network: TCP/UDP port 22000 open for sync traffic. UDP port 21027 open for local discovery.

Advanced Installation Methods

To build a resilient synchronization mesh, let us cover the installation of Syncthing across different architectures, focusing primarily on Linux servers and containers.

1. Production Linux Bare-Metal Installation (Debian/Ubuntu)

While Syncthing is often available in default repositories, I always recommend configuring the official APT repository to ensure you receive the latest updates directly from the developers.

First, install the necessary dependencies:

sudo apt update && sudo apt install curl apt-transport-https -y

Download the PGP release key:

sudo curl -fsSL -o /usr/share/keyrings/syncthing-archive-keyring.gpg https://syncthing.net/release-key.txt

Add the stable release channel to your software sources:

echo "deb [signed-by=/usr/share/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable" | sudo tee /etc/apt/sources.list.d/syncthing.list

Update your package indexes and install the daemon:

sudo apt update && sudo apt install syncthing -y

Configuring Systemd Services

Syncthing must run continuously in the background to be useful. We will manage it using systemd. Never run Syncthing as the root user. If an attacker somehow compromised the application, running as root would give them full control over your Linux filesystem.

Enable the service as a standard user (replace sysadmin with your actual Linux username):

sudo systemctl enable --now [email protected]

This binds the daemon to your user account, starting it automatically on boot using systemd. Check its status:

sudo systemctl status [email protected]

2. Docker Compose Container Deployment

For those running a modern Docker environment, deploying Syncthing as a container keeps your host system clean. This is my preferred method when managing a stack alongside other tools like Uptime Kuma and Portainer.

Create a new directory and write the following docker-compose.yml file:

version: "3"
services:
  syncthing:
    image: lscr.io/linuxserver/syncthing:latest
    container_name: syncthing
    hostname: homeserver-syncthing
    environment:
      - PUID=1000 # Map to your local non-root user UID
      - PGID=1000 # Map to your local non-root user GID
      - TZ=Etc/UTC
    volumes:
      - /opt/syncthing/config:/config
      - /mnt/storage/sync_data:/data1
    ports:
      - 8384:8384 # Web GUI port
      - 22000:22000/tcp # Sync protocol TCP port
      - 22000:22000/udp # Sync protocol QUIC port
      - 21027:21027/udp # Local discovery UDP port
    restart: unless-stopped

Bring the container up in detached mode:

docker-compose up -d

This ensures your Syncthing node spins up alongside any other secure Docker containers you have running. If you want to automate container updates, you can pair this setup with Watchtower.

3. Windows, macOS, and Android Clients

• Windows: I highly recommend using SyncTrayzor. It is a fantastic open-source wrapper for Windows that bundles the Syncthing binary, creates a system tray icon, handles startup gracefully, and includes a built-in browser view for the management GUI.
• macOS: You can use macOS Syncthing or install it via Homebrew (brew install syncthing).
• Android: Download the official Syncthing client from the Google Play Store or F-Droid. Crucial Android Tip: Modern Android versions aggressively kill background apps. You must go into your phone settings and explicitly disable battery optimization for the Syncthing app, or files will only sync when the screen is physically turned on.

Initial Configuration & Security Hardening

By default, Syncthing binds its web management GUI to the loopback address (127.0.0.1:8384). If you installed this on a headless server and need to access it from another computer on your LAN, you must change this to listen on all interfaces.

Edit the configuration file (usually located at ~/.config/syncthing/config.xml on bare-metal):

Find the <gui> tag and change the listen address:

<gui enabled="true" tls="false" debugging="false">
    <address>0.0.0.0:8384</address>
    <apikey>YOUR_RANDOM_API_KEY</apikey>
    <theme>default</theme>
</gui>

Restart the service (sudo systemctl restart [email protected]), then navigate to http://YOUR_SERVER_IP:8384 in your browser.

Securing the Dashboard

The moment you expose the GUI to your local network, you must secure it:

1. Click Actions > Settings > GUI.
2. Set a strong GUI Authentication User and GUI Authentication Password. You can generate a robust password using a reliable password manager like Vaultwarden or KeepassXC.
3. Check the box for Use HTTPS for GUI.
4. Save the settings. Syncthing will restart and generate a self-signed TLS certificate. You will need to click past the security warning in your browser to access the dashboard securely.

If you plan to access the dashboard externally over the internet, do not expose port 8384 directly. Instead, route the traffic through a reverse proxy like Nginx Proxy Manager, Traefik, or Caddy, and secure it with a valid Let’s Encrypt SSL certificate. You should also put the proxy behind a VPN connection using Tailscale or WireGuard for an extra layer of firewall security.

Practical Usage: Connecting Devices and Sharing Folders

Connecting devices in Syncthing is entirely decentralized. There is no master node; it is a true mesh.

Step 1: Pair the Peer Devices

1. On your Laptop (Node A), click Actions > Show ID. This displays the 56-character Device ID string and a QR code.
2. On your Phone (Node B), open the Syncthing app, tap Add Device, and scan the QR code displayed on Node A.
3. Within 60 seconds, Node A will display a prompt: “Device ‘Phone’ wants to connect”. Click Add Device to approve the cryptographic handshake.

Step 2: Share a Folder

1. On Node A, click Add Folder in the left panel.
2. Under the General tab, set a Folder Label (e.g., “Obsidian Notes”) and specify the absolute path on your filesystem.
3. Switch to the Sharing tab and check the box next to Node B (your Phone).
4. On Node B, a notification will appear asking if you want to accept the shared folder. Approve it and select where it should be stored locally on your phone.

The files will immediately begin syncing over the local area network.

Networking, Discovery, & NAT Traversal

Syncthing is engineered to aggressively bypass network restrictions to find peers. When two devices attempt to sync, they follow this discovery pipeline:

1. Local Discovery: Syncthing broadcasts UDP packets on port 21027 across your local LAN. If the devices are on the same Wi-Fi, they instantly connect directly.
2. Global Discovery: If you take your laptop to a coffee shop, it can no longer see your home server via local broadcast. Both devices will announce their current IP addresses to Syncthing’s public Global Discovery Servers. They then attempt to establish a direct connection over the WAN.
3. NAT Traversal: If your home server is behind a strict router, Syncthing uses UPnP (Universal Plug and Play) or NAT-PMP to dynamically open port 22000.
4. Relay Servers: If both devices are behind strict symmetric NAT firewalls and cannot establish a direct link, Syncthing will route the traffic through a public Relay Server. The data remains fully encrypted with TLS 1.3, so the relay operator cannot read your files. However, public relays are intentionally speed-limited (often capping at 50-100 Kbps).

If you frequently suffer from slow relay speeds, I highly recommend configuring port forwarding on your router manually to forward TCP/UDP 22000 directly to your Syncthing server.

Advanced File Versioning Strategies

When multiple devices have write access to a shared folder, accidental deletions or file corruption (like a ransomware attack) will instantly replicate across the entire mesh. To mitigate this, Syncthing offers robust file versioning configured on a per-folder basis.

• Trash Can Versioning: The simplest method. When a file is modified or deleted by a peer, the original version is moved into a hidden .stversions folder on your local disk. You define how many days the file stays there before permanent deletion.
• Simple File Versioning: This retains a specific number of old versions (e.g., keeping the last 5 iterations of a file).
• Staggered Versioning (Recommended): This is fantastic for syncing databases or active coding projects. It takes snapshots of changes, keeping hourly versions for the first day, daily versions for a month, and weekly versions thereafter. It operates similarly to how backup tools like Restic or BorgBackup handle snapshot retention.
• External Versioning: This passes the path of the modified file to a custom bash script. You can use this to trigger automatic git commit commands or send alerts via webhooks.

Ignore Rules (.stignore)

You rarely want to sync absolutely everything in a directory tree. For instance, syncing a Node.js project means you definitely want to ignore the massive node_modules folder.

In Syncthing, you can create a .stignore text file in the root of any shared folder.

# Ignore macOS and Windows metadata
(?d).DS_Store
(?d)Thumbs.db

# Ignore Node.js dependencies and build outputs
/node_modules
/dist
/build

# Ignore all temporary log files
*.log

The (?d) prefix is special; it tells Syncthing that it is allowed to delete these ignored files if a peer device deletes the parent folder. Without this flag, Syncthing will refuse to delete a folder if it contains ignored files, leading to frustrating “Out of Sync” errors.

Performance Optimization and Troubleshooting

Even in a well-architected setup, you may encounter syncing bottlenecks or system errors.

The Inotify Limit (Linux)

If you are syncing a folder with hundreds of thousands of small files (like a Gitea codebase or a Nextcloud data directory), Syncthing relies on the Linux kernel’s inotify subsystem to watch for real-time changes. By default, most Linux distributions set this limit too low, resulting in Syncthing falling back to slow, CPU-intensive periodic scanning.

You can permanently increase the file watcher limit by editing your sysctl configuration:

echo "fs.inotify.max_user_watches=204800" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

This simple optimization dramatically reduces CPU usage and makes file syncs nearly instantaneous.

Debugging with the CLI

If you are managing Syncthing on a headless server without GUI access, you can debug it via its REST API. Extract your API key from the config.xml file, and use curl to query the daemon’s status:

curl -s -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8384/rest/system/status

This is particularly useful if you want to pipe the JSON output into monitoring dashboards like Grafana, Prometheus, or Netdata.

Backup & Disaster Recovery Integration

Syncthing is a synchronization tool, not a backup tool. If you delete a file on your phone, Syncthing will faithfully delete it on your server. While file versioning offers a buffer, it does not replace a true 3-2-1 backup strategy.

You should designate one of your Syncthing nodes (typically a home server or NAS) as the “Master Vault.” On this server, configure a dedicated backup utility like Restic, Duplicati, or plain rsync to take daily encrypted snapshots of your Syncthing directories and push them to off-site object storage (like an AWS S3 bucket, MinIO, or a cheap Hetzner storage box).

By combining Syncthing’s real-time replication with Restic’s immutable snapshots, you achieve complete data sovereignty and disaster resilience.

Alternatives and Comparisons

How does Syncthing compare to other popular tools?

• Nextcloud / OwnCloud: Nextcloud is a full-featured cloud suite offering calendars, contacts, and collaborative document editing via a central web interface, often backed by PostgreSQL or MariaDB. Syncthing is strictly for file synchronization. Syncthing is vastly lighter on system resources and does not require a database.
• Resilio Sync: Formerly BitTorrent Sync, Resilio is highly performant but is proprietary, closed-source software with commercial tiers. Syncthing is 100% open-source and community-driven.
• rsync / scp: These classic command-line tools are great for one-off transfers or scheduled cron jobs, but they do not provide real-time, bi-directional continuous synchronization.
• Tailscale / WireGuard: These create secure VPN meshes. You can actually run Syncthing over a Tailscale network to eliminate the need for global discovery or public relay servers, keeping all sync traffic strictly within your private subnet.

Conclusion

Syncthing is a masterclass in decentralized software engineering. It frees your data from commercial cloud silos, ensures your privacy through robust TLS encryption, and operates efficiently on almost any hardware you throw at it. Whether you are using it to mirror an Obsidian or Logseq markdown vault across your devices, back up your Android camera roll to an Immich server, or distribute Stirling-PDF documents securely across a corporate team, Syncthing is an indispensable utility.

By taking the time to set up proper systemd services, implementing strategic .stignore rules, and configuring staggered versioning, you can build a private sync mesh that is more reliable and secure than anything you could subscribe to.

Official Documentation

Always refer to the primary sources for the most up-to-date syntax, API endpoints, and configuration flags:

• Syncthing Official Documentation: https://docs.syncthing.net/
• Syncthing GitHub Repository: https://github.com/syncthing/syncthing
• Syncthing Support Forum: https://forum.syncthing.net/
• SyncTrayzor (Windows GUI Wrapper): https://github.com/canton7/SyncTrayzor

Frequently Asked Questions

What is the difference between Syncthing and Nextcloud?

Syncthing is a decentralized, peer-to-peer file synchronization tool that connects devices directly without a central server. Nextcloud is a centralized, self-hosted cloud platform that acts as a central hub (like Google Drive) and offers additional features like calendars, contacts, and web-based collaborative document editing.

Can Syncthing sync files to iOS devices (iPhones and iPads)?

Currently, there is no official native Syncthing client for iOS due to Apple’s restrictive background process limitations. However, there is a third-party open-source app called Möbius Sync available on the App Store that provides limited Syncthing functionality on iOS.

Is my data secure if Syncthing uses a public relay server?

Yes. Syncthing utilizes end-to-end TLS 1.3 encryption for all data transfers. If a direct connection cannot be made and a public relay is used, the relay operator only sees encrypted traffic and cannot read your filenames, folder structures, or file contents.

Does Syncthing consume a lot of battery on Android phones?

Syncthing can consume battery if it is constantly scanning large directories for changes. To optimize this, you can configure the Android app to only sync when connected to Wi-Fi, only sync when the device is charging, or increase the interval for background periodic scans.

How do I handle file conflicts when two devices modify a file simultaneously?

Syncthing detects modification conflicts automatically. If a conflict occurs, it preserves both versions of the file by appending .sync-conflict- along with the date and the modifying device’s ID to the filename. You can then review both files manually and keep the correct version.

What happens if I delete a file on one synced device?

By default, Syncthing acts as a mirror; deleting a file on your phone will delete it on your server. To protect against accidental data loss, you should enable File Versioning (such as Trash Can or Staggered versioning) in the folder settings, which will keep deleted files in a hidden .stversions folder for easy recovery.

Can I run Syncthing securely without exposing port 8384 to the internet?

Yes. You should never expose port 8384 (the web management GUI) directly to the public internet. If you need remote access to the dashboard, use an SSH tunnel, a secure VPN like Tailscale, or a reverse proxy like Nginx Proxy Manager secured with external authentication and SSL.

Why is my Syncthing setup stuck syncing at 99%?

This usually indicates a file permission or locking issue on the host operating system. Syncthing may not have the read/write permissions required to modify a specific file, or another application might have locked the file. Check the web GUI logs to identify the exact file causing the block.

Can I limit the network bandwidth Syncthing uses?

Yes. In the Syncthing web GUI, navigate to Actions > Settings > Connections. Here, you can define global limits for outgoing and incoming rate limits (measured in KiB/s) to ensure Syncthing does not saturate your home network or internet connection.

How do I completely remove a device from my Syncthing mesh?

To remove a device, open the Syncthing web GUI, click on the device name in the Remote Devices panel, select Edit, and then click the Remove button. You must also uncheck that device from any folders you were sharing with it to stop sync attempts.