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.

What if you could synchronize your files between your phone, laptop, and server without paying a monthly fee or uploading your data to third-party servers?

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 hard drives.

In this deep-dive guide, we will explore the architecture of Syncthing, cover installation across multiple systems (including Docker-compose deployments), configure peer connection trusts, set up file versioning policies, and troubleshoot common networking and file-watching errors.

1. What is Syncthing? Core Architecture & Design Philosophy

Syncthing replaces centralized cloud databases with a secure, decentralized synchronization mesh.

Centralized Cloud Storage:
[ Device A ] ──► [ Big Tech Server (Data Center) ] ◄── [ Device B ]

Decentralized P2P Sync (Syncthing):
[ Device A ] <─────── Encrypted Direct Link ───────> [ Device B ]

The Block Exchange Protocol (BEP v1)

Under the hood, Syncthing uses the Block Exchange Protocol (BEP v1) to sync directories.

1. File Chunking: When a file is added or modified in a sync folder, 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 exchange lists of block hashes for each file.
4. Delta Synchronization: Instead of transferring the entire modified file, Syncthing compares the hashes and transmits only the blocks that have changed. This saves significant bandwidth when modifying large databases (like KeePass .kdbx files or browser profiles).

Cryptographic Security & Device Identities

• TLS 1.3 Encryption: All communication is secured using TLS 1.3. Eavesdroppers on public networks or ISP lines cannot read your files.
• Cryptographic Device IDs: Syncthing does not use usernames or passwords to pair devices. Instead, each device generates a unique 56-character Device ID (which is 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 (like a rented VPS or a public cloud backup endpoint). The files are encrypted locally before transmission, allowing the untrusted node to sync the blocks without ever knowing the filenames or file contents.

2. Advanced Installation Walkthrough

To build a robust synchronization mesh, let us install Syncthing across different system architectures.

1. Production Linux Installation (Debian/Ubuntu)

To get updates directly from the developers, configure the official APT repository:

# Install curl to fetch repository keys
sudo apt update && sudo apt install curl -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 package indexes and install the daemon
sudo apt update && sudo apt install syncthing -y

Configuring Systemd Services

To run Syncthing automatically in the background, you should configure it as a systemd service. Avoid running Syncthing as the root user for security reasons; instead, run it under a standard user account. You have two options:

Option A: System-Level Service (Recommended for Servers)

This runs Syncthing as a system daemon bound to a specific user account. It starts automatically at system boot, even if no users have logged in.

• Enable the service (replace suresh with your Linux username):

  sudo systemctl enable --now [email protected]

  How it works: The package manager installs a template file at /lib/systemd/system/[email protected]. The name after the @ symbol is passed to the service file as the %i variable, running the daemon under that user’s permissions and environment.

Option B: User-Level Service (Recommended for Desktops)

This runs Syncthing within the user’s private systemd session. It is useful on desktop workstations where you want the daemon to manage files in your home directory.

• Enable the user-level service:

  systemctl --user enable --now syncthing.service

• Enable System Lingering: By default, user-level systemd services are killed when the user logs out of their terminal or GUI session. To allow your user-level Syncthing instance to continue running when you log out, enable user lingering:

  loginctl enable-linger suresh

2. Headless Docker-Compose Deployment

For home servers, running Syncthing inside a Docker container simplifies volume mapping and updates. Here is a production-ready docker-compose.yml file:

version: "3"
services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: homeserver-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - ./config:/var/syncthing/config
      - /mnt/data/shares:/var/syncthing/shares
    ports:
      - 8384:8384 # Web GUI port
      - 22000/tcp:22000/tcp # Sync protocol TCP port
      - 22000/udp:22000/udp # Sync protocol QUIC port
      - 21027/udp:21027/udp # Local discovery UDP port
    restart: unless-stopped

Launch the service by running:

docker-compose up -d

3. Windows (SyncTrayzor)

While you can run the raw Syncthing binary on Windows, we recommend installing SyncTrayzor. It is a Windows utility wrapper that bundles Syncthing, provides a system tray icon, handles automatic startup, and includes a built-in browser window to access the Web GUI.

4. Android

Download the official client app from F-Droid or the Google Play Store.

• Optimization Tip: Android’s battery saver can suspend background sync processes. Go to your phone’s Settings > Apps > Syncthing > Battery, and select Unrestricted (or turn off battery optimization) to ensure real-time syncing.

3. Configuring the Web GUI & Initial Security Hardening

Once launched, access the management dashboard by navigating to the following address in your browser: http://127.0.0.1:8384

Web GUI Dashboard Layout:
+------------------------------------+------------------------------------+
|  [ Folders Panel ]                 |  [ Devices Panel ]                 |
|  - Sync Directory 1 (Up to date)   |  - Desktop Laptop (Connected)      |
|  - Backups (Syncing 82%)           |  - Android Phone (Connected)       |
+------------------------------------+------------------------------------+
|  [ System Logs & Status Indicators ]                                    |
+-------------------------------------------------------------------------+

Initial Security Steps:

1. Configure Admin Credentials: By default, the GUI has no password. Go to Actions > Settings > GUI, set a strong username and password, and check the Use HTTPS for GUI option.
2. Verify Listening Address: By default, Syncthing binds the GUI to loopback address 127.0.0.1:8384. If you are hosting it on a headless server and want to access it across your local network, change the GUI Listen Address to 0.0.0.0:8384. Ensure your server’s firewall blocks external public access to this port.

4. Connecting Devices & Syncing Folders

Connecting devices and sharing folders follows a simple trust model:

Step 1: Pair the Devices

1. On Device A (Computer), click Actions > Show ID to display the Device ID string and QR code.
2. On Device B (Phone), tap Add Device and scan the QR code. Give the device a friendly name (e.g., “My Laptop”).
3. On Device A, a prompt will appear within a minute: Device "My Phone" wants to connect. Click Add Device.

Step 2: Share a Folder

1. On your computer’s dashboard, click Add Folder under the Folders column.
2. Under the General tab, set a descriptive Folder Label (e.g., “Obsidian Notes”) and choose the absolute Folder Path on your disk.
3. Go to the Sharing tab and check the box next to your phone’s name.
4. On your phone, tap Accept on the shared folder notification and choose the local storage directory. Syncthing will start syncing the folder.

5. Network Routing, Discovery, & NAT Traversal

Syncthing is designed to find peers and sync files across varying network architectures. It uses several discovery methods to connect:

Network Discovery Pipeline:
[ Local Discovery (Port 21027 UDP Broadcast) ] ──► (Local Connection OK) ──► Direct Sync
                      │
                      ▼ (Failed)
[ Global Discovery (Hash Announcement Server) ] ──► [ NAT Traversal (UPnP) ] ──► Direct WAN Sync
                      │
                      ▼ (Failed)
[ Relaying Protocol (Encrypted BEP Relay) ] ──► Encrypted Relay Sync (Max 50-100 Kbps limit)

1. Local Discovery: Broadcasts announcement packets on UDP port 21027 across your local network interface. If your devices are on the same Wi-Fi network, they connect directly without querying external servers.
2. Global Discovery: If your devices are on different networks (e.g., home PC and phone on mobile data), they query Syncthing’s global discovery servers. The devices announce their encrypted Device ID hashes and public IP/port locations.
3. NAT Traversal (UPnP): If your devices are behind firewalls, Syncthing attempts to open ports dynamically using UPnP (Universal Plug and Play) or NAT-PMP.
4. Syncthing Relays: If a direct connection cannot be established, Syncthing routes traffic through public Relay Servers. Relayed connections are encrypted using the standard TLS protocol, meaning the relay host cannot read your files. However, relay speeds are restricted to protect public bandwidth.
   • Self-Hosting Tip: If you run into strict NAT configurations, you can host your own private relay server to enjoy unrestricted speeds.

6. Advanced File Versioning Strategies

Syncthing includes built-in file versioning to protect against accidental deletions, file corruption, or ransomware attacks. You can configure versioning individually for each folder:

• Trash Can Versioning: When a file is deleted or modified by a peer device, Syncthing moves the original file into a hidden .stversions directory. You can configure how many days these files are retained before being permanently deleted.
• Simple File Versioning: Keeps a set number of historical versions of each file (e.g., keeping the last 5 modifications of a file before overwriting it).
• Staggered File Versioning: Retains files at regular intervals, keeping hourly versions for the first day, daily versions for the first month, and weekly versions thereafter.
• External File Versioning: Executes a custom shell script on your server whenever a file change occurs, allowing you to trigger custom backups or Git commits.

Staggered Versioning Schedule:
[ Day 1: Hourly Snapshots ] ──► [ Month 1: Daily Snapshots ] ──► [ Year 1: Weekly Snapshots ]

7. Ignoring Files (.stignore)

You don’t always need to sync every file in a directory. For example, you may want to exclude node module folders, operating system system files (Thumbs.db, .DS_Store), or compiler outputs.

To exclude these, create a plain text file named .stignore in the root of your shared folder and define your exclude patterns:

# Ignore OS generated metadata files
(?d).DS_Store
(?d)Thumbs.db

# Ignore build output and dependency folders
/node_modules
/bin
/obj
*.tmp
*.log

# Include a subfolder that would otherwise match an ignore pattern
!/bin/release

Deconstructing the .stignore Syntax

• The Directory Prefix (/): A pattern starting with a forward slash / matches files and folders only in the root of the shared directory. For example, /node_modules ignores the folder at the root level, but will not ignore /src/subproject/node_modules. A pattern without a leading slash matches anywhere in the directory tree.
• The Deletable Prefix ((?d)): Instructs Syncthing that it is safe to delete these ignored files if they prevent a parent folder from being deleted during synchronization. If this flag is omitted, a folder deletion on a peer device will fail on your local device if it contains un-synced, ignored files.
• The Exception Prefix (!): Inverts the matching rule, creating an override exception. For example, if you ignore all log files with *.log, you can force Syncthing to sync a specific log by adding !important.log. Exceptions must be placed above the general ignore rules to take effect.
• Case Insensitivity ((?i)): By default, Syncthing matches filenames using case-sensitive rules. Prepend (?i) to make a match case-insensitive, e.g., (?i)private* will match private.txt and PRIVATE.JPG.
• Recursive Wildcards (**): Standard wildcards * match characters within a single folder level. A double wildcard ** matches directories recursively. For example, src/**/temp/ will ignore the temp folder at any level under the src directory tree.

8. Diagnostic Troubleshooting & Optimization

Use this matrix to identify and resolve common issues:

Technical CLI Debugging & REST API Queries

If you are running Syncthing on a headless server, you can query its internal status directly via its REST API. First, locate your API Key in your config.xml file (usually located at ~/.config/syncthing/config.xml or /var/syncthing/config/config.xml inside Docker):

# Extract the API key from the config file
grep -i "apikey" ~/.config/syncthing/config.xml

Once you have your API key, you can make HTTP requests to query the system status:

• Check system health and uptime:

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

• Query the sync status of a specific folder:

  curl -s -H "X-API-Key: YOUR_API_KEY_HERE" http://127.0.0.1:8384/rest/db/status?folder=YOUR_FOLDER_ID

• View active network connections and discovery status:

  curl -s -H "X-API-Key: YOUR_API_KEY_HERE" http://127.0.0.1:8384/rest/system/connections

9. Cloud Synchronization Comparison

The table below highlights the differences between Syncthing and traditional cloud services:

10. Conclusion

Setting up Syncthing provides you with a private, secure, and decentralized file synchronization mesh. Whether you are using it to keep your Obsidian notes synced across devices, back up your phone’s camera roll to your computer, or push configuration updates to a remote Linux server, Syncthing gives you complete control over your data.

Interested in pairing Syncthing with other self-hosted services? Read our step-by-step guides on configuring a secure Vaultwarden Password Manager or managing your private cloud storage with Nextcloud today!

Frequently Asked Questions (FAQ)

Q: How does Syncthing synchronize files differently from traditional cloud storage? A: Syncthing uses a decentralized, peer-to-peer (P2P) architecture, meaning your files are synced directly between your devices over encrypted connections without being stored on a central third-party server.

Q: Is my data secure when using Syncthing on public networks? A: Yes, all data transmission between devices is secured with TLS 1.3 encryption, ensuring that files cannot be intercepted or read by eavesdroppers or ISPs.

Q: How do I link devices in Syncthing without using accounts or passwords? A: Syncthing relies on unique 56-character Cryptographic Device IDs generated from TLS certificates. Devices must explicitly exchange and approve these IDs to establish a trusted connection.

Q: What should I do if my Syncthing devices are stuck on “Disconnected”? A: Ensure that firewall rules are not blocking Syncthing. Specifically, verify that TCP and UDP port 22000 are open, which are used for the sync protocol.

Q: How can I prevent Syncthing from synchronizing specific files or folders? A: You can create a .stignore file in the root of your shared folder and define exclusion patterns for files or directories you want Syncthing to ignore, such as system metadata or temporary build folders.