Syncthing: Peer-to-Peer File Synchronization

Take control of your file synchronization with Syncthing, a continuous peer-to-peer file sync solution that keeps your data private, secure, and always available across all your devices. This comprehensive guide walks you through deploying your own decentralized sync infrastructure.

Difficulty: Intermediate Estimated Time: 40 minutes Last Updated: December 2025 Target Audience: Homelab enthusiasts, privacy-conscious users, small teams

---

What You’ll Learn

• Deploy Syncthing using Docker and native installations
• Configure device pairing and folder sharing
• Implement ignore patterns for selective sync
• Set up file versioning and conflict resolution
• Configure relay servers and discovery
• Optimize performance for large file sets
• Troubleshoot common synchronization issues
• Integrate Syncthing with backup strategies

Prerequisites

Required Knowledge

• Basic Docker and Docker Compose familiarity (for containerized deployment)
• Linux command-line basics
• Basic networking concepts (ports, firewalls)
• File system and permissions understanding

Required Infrastructure

• Linux server, NAS, or desktop (Ubuntu 22.04+, Debian 11+)
• Minimum: 512 MB RAM, 1 GHz processor
• Recommended: 2+ cores, 2-4 GB RAM, sufficient storage for synced files
• Network connectivity between devices
• Optional: Domain name for remote access

Pre-Deployment Checklist

• Devices identified for synchronization
• Network connectivity verified between devices
• Firewall rules planned (port 22000 TCP/UDP)
• Storage space allocated for synchronized files
• Backup strategy for synced data

---

1. Understanding Syncthing

What is Syncthing?

Syncthing is an open-source continuous file synchronization program that synchronizes files between two or more computers in real time. Unlike cloud-based solutions like Dropbox or Google Drive, Syncthing operates on a peer-to-peer model with no central server, keeping your data completely private and under your control.

Key Features:

• Decentralized Architecture: No central server - devices communicate directly
• End-to-End Encryption: All data encrypted in transit using TLS
• Cross-Platform: Works on Linux, Windows, macOS, Android, and more
• Open Source: Fully auditable code, active community development
• Privacy-Focused: No data collection, no cloud storage, no third parties
• Selective Sync: Choose which folders to sync between devices
• Version Control: Built-in file versioning and conflict resolution
• Bandwidth Control: Limit sync speeds to avoid network congestion

Why Choose Syncthing?

How Syncthing Works

The Sync Process:

Device A                        Device B
┌─────────────┐                ┌─────────────┐
│  Syncthing  │                │  Syncthing  │
│  Instance   │◄──Discovery───►│  Instance   │
└─────────────┘                └─────────────┘
       │                              │
       │         1. Device Discovery  │
       │         2. Authentication    │
       │         3. Folder Exchange   │
       │         4. File Indexing     │
       │         5. Block Sync        │
       │         6. Conflict Resolve  │
       │                              │
    Local Files◄────Sync────────►Local Files

Synchronization Steps:

1. Discovery: Devices find each other using global/local discovery servers
2. Authentication: Devices verify identity using unique device IDs
3. Folder Configuration: Users specify which folders to sync
4. Indexing: Each device builds an index of files and blocks
5. Synchronization: Changed blocks are transferred between devices
6. Conflict Resolution: Conflicting changes are handled via versioning

---

2. Installation Methods

Method 1: Docker Deployment (Recommended for Homelabs)

Docker deployment provides consistency and easy updates.

Create directory structure:

# Create Syncthing directories
mkdir -p /opt/syncthing/{config,data}
cd /opt/syncthing

Create docker-compose.yml:

version: '3.8'

services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: syncthing-server
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    ports:
      # Web UI
      - "8384:8384"
      # TCP file transfers
      - "22000:22000/tcp"
      # UDP file transfers
      - "22000:22000/udp"
      # Local discovery broadcasts
      - "21027:21027/udp"
    volumes:
      # Syncthing configuration
      - ./config:/var/syncthing/config
      # Data to synchronize
      - ./data:/var/syncthing/data
      # Optional: Additional sync folders
      - /mnt/storage/documents:/documents
      - /mnt/storage/photos:/photos
    networks:
      - syncthing-network

networks:
  syncthing-network:
    driver: bridge

Deploy the container:

# Start Syncthing
docker-compose up -d

# View logs
docker-compose logs -f syncthing

# Check status
docker-compose ps

Access the web UI:

Open your browser to http://your-server-ip:8384

Method 2: Native Installation (Linux)

For maximum performance on dedicated systems.

Ubuntu/Debian:

# Add the Syncthing repository
sudo curl -o /usr/share/keyrings/syncthing-archive-keyring.gpg   https://syncthing.net/release-key.gpg

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 list
sudo apt update

# Install Syncthing
sudo apt install syncthing

# Enable and start service
sudo systemctl enable syncthing@$USER.service
sudo systemctl start syncthing@$USER.service

# Check status
systemctl status syncthing@$USER.service

Accessing the web UI:

By default, Syncthing listens on http://127.0.0.1:8384. For remote access:

# Edit config to allow remote access
nano ~/.config/syncthing/config.xml

Find this section:

<gui enabled="true" tls="false" debugging="false">
    <address>127.0.0.1:8384</address>
    <apikey>your-api-key</apikey>
    <theme>default</theme>
</gui>

Change to:

<gui enabled="true" tls="false" debugging="false">
    <address>0.0.0.0:8384</address>
    <user>admin</user>
    <password>your-secure-password-hash</password>
    <apikey>your-api-key</apikey>
    <theme>default</theme>
</gui>

Generate password hash:

# This command will prompt for a password and output the hash
echo -n "YourPassword" | sha1sum

Restart Syncthing after configuration changes:

systemctl restart syncthing@$USER.service

Method 3: Android Installation

Install from Google Play Store or F-Droid:

1. Search for “Syncthing” in your app store
2. Install the official Syncthing app
3. Grant necessary permissions (storage, background operation)
4. Open the app to access settings

---

3. Initial Configuration

Securing the Web UI

Set up authentication (critical for remote access):

1. Access the web UI
2. Go to Actions → Settings → GUI
3. Set a strong username and password
4. Consider enabling HTTPS for the web UI
5. Click Save

Enable HTTPS (recommended):

# Generate self-signed certificate (for testing)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Move certificates to config directory
mv cert.pem key.pem ~/.config/syncthing/
# Or for Docker: /opt/syncthing/config/

Update config.xml:

<gui enabled="true" tls="true" debugging="false">
    <address>0.0.0.0:8384</address>
</gui>

Understanding Device IDs

Each Syncthing instance has a unique device ID - a cryptographic hash used for authentication.

Find your device ID:

1. Open the web UI
2. Click Actions → Show ID
3. Note the QR code and text ID

Device IDs look like:

MRIW7OK-6X7....-EXAMPLE-7777777

This ID is used to pair devices securely.

---

4. Device Pairing and Folder Sharing

Adding Remote Devices

On Device A (adding Device B):

1. Open Syncthing web UI on Device A
2. Click Add Remote Device (bottom right)
3. Enter Device B’s device ID
4. Give it a friendly name (e.g., “Laptop”, “Phone”, “NAS”)
5. Configure sharing options:
   • Introducer: Allow this device to introduce other devices (optional)
   • Auto Accept: Automatically accept folders shared by this device
6. Click Save

On Device B (accepting the pairing):

1. A notification will appear in Device B’s UI
2. Click the notification or go to pending devices
3. Verify the device ID matches Device A
4. Click Add Device

Verification:

Both devices should now show as “Connected” in their respective UIs.

Creating and Sharing Folders

Create a shared folder:

1. In the web UI, click Add Folder
2. Configure folder settings:
   • Folder Label: Friendly name (e.g., “Photos”, “Documents”)
   • Folder ID: Auto-generated unique ID
   • Folder Path: Local path to sync
3. Under Sharing, select which devices should have access
4. Configure folder type:
   • Send & Receive: Bidirectional sync (most common)
   • Send Only: Only send changes, don’t receive
   • Receive Only: Only receive changes, don’t send
5. Click Save

On the receiving device:

1. A notification appears: “Device wants to share folder”
2. Click Add
3. Choose local path for the folder
4. Verify settings
5. Click Save

Folder sync begins automatically.

Folder Types Explained

Send & Receive (Default):

Device A ←──────────────────→ Device B
  Files synchronized in both directions
  Changes on either side propagate

Send Only:

Device A ───────────────────→ Device B
  Only Device A's changes sync to B
  Changes on B are ignored
  Useful for: Backup sources, read-only distributions

Receive Only:

Device A ←───────────────────  Device B
  Only receives changes from other devices
  Local changes not synchronized
  Useful for: Backup targets, client devices

---

5. Advanced Configuration

Ignore Patterns

Prevent specific files or folders from syncing using ignore patterns.

Access ignore patterns:

1. Click on a folder
2. Go to Edit → Ignore Patterns

Common patterns:

# Ignore specific file types
*.tmp
*.log
*.cache
~*
*.swp

# Ignore directories
node_modules/
.git/
.vscode/
__pycache__/

# Ignore system files
.DS_Store
Thumbs.db
desktop.ini

# Ignore specific files
config.local.json
.env

# Pattern examples:
# * matches any sequence of characters
# ? matches single character
# ** matches any number of directories
# // comments

# Ignore all JPGs except in Photos directory
(?d)*.jpg
(?i)Photos/**/*.jpg

# Complex patterns
(?d)temp_*
(?d)backup_20??_??_??/

Pattern modifiers:

• (?i) - Case insensitive
• (?d) - Delete (remove file if it matches)
• !pattern - Negate (include files matching this pattern)

Example .stignore file:

# Development files
node_modules
.git
.vscode
*.log

# System files
.DS_Store
Thumbs.db

# Temporary files
*.tmp
*.temp
~*

# Large media (don't sync originals)
*.psd
*.ai
*.raw

# But do sync final exports
!exports/*.jpg
!exports/*.png

File Versioning

Protect against accidental deletions or unwanted changes.

Enable versioning:

1. Click on a folder
2. Go to Edit → File Versioning
3. Choose a versioning strategy

Versioning Options:

1. Trash Can File Versioning (Recommended)

• Deleted/changed files moved to .stversions folder
• Files cleaned up after configurable number of days
• Lightweight and simple

Configuration:
Clean out after (days): 30

2. Simple File Versioning

• Keep a specified number of old versions
• Files renamed with timestamp
• No automatic cleanup

Configuration:
Keep versions: 5

3. Staggered File Versioning

• Advanced: Keep versions at different intervals
• More recent changes kept in more detail
• Older changes gradually thinned out

Configuration:
Maximum Age: 365 days
Versions Path: (leave empty for .stversions)

4. External File Versioning

• Use custom scripts for versioning
• Advanced: Full control over version management

Example versioning workflow:

Original file: document.txt

User edits → Syncthing creates:
.stversions/
  └── document.txt~20251216-123456
  └── document.txt~20251215-095830
  └── document.txt~20251214-174422

Bandwidth and Resource Limits

Configure bandwidth limits:

1. Go to Actions → Settings → Connections
2. Set limits:
   • Download Rate: Limit incoming sync speed
   • Upload Rate: Limit outgoing sync speed
3. Use 0 for unlimited

Examples:

Home network (unlimited): 0 kbps
Slow connection: 1000 kbps (1 Mbps)
Mobile tethering: 500 kbps

Advanced resource limits:

# For Docker deployments, limit container resources
services:
  syncthing:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

Relay Servers and Discovery

Global Discovery:

Syncthing uses global discovery servers to help devices find each other over the internet.

• Default: Enabled
• Purpose: NAT traversal, finding devices across networks
• Privacy: Only device IDs shared, not file data

Disable global discovery (for local-only sync):

1. Go to Actions → Settings → Connections
2. Uncheck Enable Global Discovery
3. Uncheck Enable Relay

Local Discovery:

Finds devices on the same local network via UDP broadcasts.

• Port: 21027/UDP
• Fast device discovery on LAN

Relay Servers:

When direct connections fail (strict firewalls, NAT), relay servers forward encrypted traffic.

• Default relays provided by Syncthing community
• Can host your own relay server
• Traffic is still encrypted end-to-end

Custom discovery/relay servers:

# In config.xml or web UI:
# Settings → Connections → Sync Protocol Listen Addresses
tcp://0.0.0.0:22000
relay://your-relay-server.example.com:22067

---

6. Real-World Use Cases

Use Case 1: Multi-Device Document Sync

Scenario: Keep work documents synchronized across desktop, laptop, and NAS.

Configuration:

Desktop (Send & Receive)
    ↕
  NAS (Send & Receive) ← Central hub
    ↕
Laptop (Send & Receive)

Setup:

1. On NAS: Create folder /mnt/storage/documents
2. Share with desktop and laptop
3. Both endpoints accept and configure local paths
4. Enable versioning on all devices (30 days)
5. Add ignore patterns for temp files

Benefits:

• Always have latest files on all devices
• NAS acts as always-on sync hub
• Automatic versioning protects against mistakes

Use Case 2: Phone Photo Backup

Scenario: Automatically sync phone photos to home server.

Configuration:

Android Phone (Send Only)
    →
Home Server (Receive Only)
    →
Backup System (external)

Setup on Android:

1. Install Syncthing from Play Store/F-Droid
2. Create folder pointing to /DCIM/Camera
3. Set folder type: Send Only
4. Share with home server
5. Enable sync on Wi-Fi only (battery saving)

Setup on server:

1. Accept folder share
2. Set folder type: Receive Only
3. Configure path: /mnt/storage/photos/phone_backup
4. Enable versioning (prevent accidental deletions)

Optional automation:

#!/bin/bash
# /opt/scripts/organize_photos.sh
# Run daily to organize synced photos

SOURCE="/mnt/storage/photos/phone_backup"
DEST="/mnt/storage/photos/organized"

# Organize by date using exiftool
exiftool -r '-FileName<DateTimeOriginal'   -d "$DEST/%Y/%m/%d/%Y%m%d_%H%M%S.%%e"   "$SOURCE"

Use Case 3: Distributed Team Collaboration

Scenario: Small team shares project files without cloud services.

Configuration:

Team Member A (Send & Receive)
         ↕
Central Server (Send & Receive)
         ↕
Team Member B (Send & Receive)
         ↕
Team Member C (Send & Receive)

Setup:

1. Set up central server as sync hub (always online)
2. All team members connect to central server
3. Create separate folders for different projects
4. Enable versioning (30+ days)
5. Use ignore patterns for personal config files

Folder structure:

/projects/
  ├── project-alpha/
  │   ├── .stignore (ignore .vscode, node_modules)
  │   └── README.md
  ├── project-beta/
  └── shared-resources/

.stignore for development projects:

# Dependencies
node_modules/
vendor/
venv/
.venv/

# IDE
.vscode/
.idea/
*.code-workspace

# Build artifacts
dist/
build/
*.o
*.pyc

# Local config
.env.local
config.local.*

# OS files
.DS_Store
Thumbs.db

Use Case 4: Selective Server Sync

Scenario: Sync specific folders from multiple servers to a central location.

Configuration:

Web Server (/var/www/backups) → Send Only
    ↓
Database Server (/var/backups) → Send Only
    ↓
Media Server (/mnt/media/new) → Send Only
    ↓
Central Backup Server → Receive Only
    (/mnt/storage/server-backups/)

Benefits:

• Centralized backup collection
• No changes to production servers
• Minimal resource usage (one-way sync)

---

7. Performance Optimization

Tuning for Large File Sets

For millions of files:

# Increase file descriptor limits
ulimit -n 65536

# For systemd services, edit unit file:
sudo systemctl edit syncthing@$USER.service

Add:

[Service]
LimitNOFILE=65536

Database optimization:

Syncthing uses a database to track file metadata. For very large folders:

1. Use SSD storage for config directory
2. Ensure adequate RAM (1GB+ for large file sets)
3. Consider folder splitting (multiple smaller folders vs one huge folder)

Network Optimization

Direct connections preferred:

Ensure devices can connect directly (not via relay):

1. Forward port 22000 TCP/UDP on your router
2. Configure static IPs for homelab devices
3. Use local discovery on LAN

Check connection type:

In web UI, click on a device to see:

• Direct connection: Fast, no relay overhead
• Relay connection: Slower, uses community servers

Optimize sync scheduling:

# For Docker deployments with scheduled sync
# (pause Syncthing during high-usage hours)

# In crontab:
# Pause at 9 AM (work hours)
0 9 * * * docker pause syncthing
# Resume at 6 PM
0 18 * * * docker unpause syncthing

Resource Usage Reduction

Limit CPU usage:

# Docker deployment
services:
  syncthing:
    deploy:
      resources:
        limits:
          cpus: '0.5'  # Limit to 50% of one core

Reduce scan frequency:

1. Go to folder settings
2. Advanced → Rescan Interval
3. Increase from default (60s) to 3600s (1 hour) for stable folders

Disable unused features:

1. Settings → Connections
2. Disable global discovery if only syncing locally
3. Disable relay if direct connections work
4. Disable NAT traversal if not needed

---

8. Security Best Practices

Encryption and Authentication

Transport Encryption:

All Syncthing connections are encrypted by default using TLS 1.2+.

• No configuration needed
• Automatic certificate generation per device
• Perfect forward secrecy

Device Authentication:

Only devices with approved device IDs can connect.

Security checklist:

• Web UI protected with strong password
• HTTPS enabled for web UI (especially if accessible remotely)
• Firewall configured to limit access to port 8384
• Device IDs verified when adding new devices
• Unused devices removed regularly

Network Segmentation

Isolate Syncthing:

# Docker deployment with isolated network
services:
  syncthing:
    networks:
      - syncthing-isolated

networks:
  syncthing-isolated:
    driver: bridge
    internal: false  # Set to true for no internet access
    ipam:
      config:
        - subnet: 172.28.0.0/16

Firewall rules (UFW example):

# Allow Syncthing ports from specific subnet only
sudo ufw allow from 192.168.1.0/24 to any port 22000 proto tcp
sudo ufw allow from 192.168.1.0/24 to any port 22000 proto udp
sudo ufw allow from 192.168.1.0/24 to any port 21027 proto udp

# Allow web UI only from local network
sudo ufw allow from 192.168.1.0/24 to any port 8384 proto tcp

Read-Only and Untrusted Device Modes

Protect important folders:

1. Set critical folders to Send Only on the source
2. Use Receive Only on backup destinations
3. Never use Send & Receive for backups

Untrusted devices:

Settings → Devices → [Select Device] → Advanced
☑ Untrusted

Effects:
- Device cannot modify ignore patterns
- Device cannot introduce other devices
- Useful for: Shared laptops, mobile devices

---

9. Backup Integration

Syncthing + Restic Workflow

Combine Syncthing for sync with Restic for versioned backups.

Architecture:

Devices → Syncthing Sync → Central Server
                                ↓
                            Restic Backup
                                ↓
                          S3/SFTP/Local

Backup script:

#!/bin/bash
# /opt/scripts/backup-syncthing.sh

# Syncthing data directory
SOURCE="/opt/syncthing/data"

# Restic repository
export RESTIC_REPOSITORY="s3:s3.amazonaws.com/my-backup-bucket"
export RESTIC_PASSWORD_FILE="/root/.restic-password"

# Backup
restic backup "$SOURCE"   --tag syncthing   --exclude="*.tmp"   --exclude=".stfolder"

# Prune old backups
restic forget   --keep-daily 7   --keep-weekly 4   --keep-monthly 12   --prune

Automate with cron:

# Daily backup at 2 AM
0 2 * * * /opt/scripts/backup-syncthing.sh >> /var/log/syncthing-backup.log 2>&1

Syncthing + Borg Backup

Similar workflow using Borg for deduplication.

#!/bin/bash
# /opt/scripts/borg-syncthing.sh

export BORG_REPO="/mnt/backup/syncthing-borg"
export BORG_PASSPHRASE="your-secure-passphrase"

# Create backup
borg create   --stats   --compression zstd,3   --exclude "*.tmp"   ::'{hostname}-{now:%Y-%m-%d_%H:%M:%S}'   /opt/syncthing/data

# Prune old archives
borg prune   --keep-daily 7   --keep-weekly 4   --keep-monthly 12

---

10. Troubleshooting Common Issues

Issue 1: Devices Not Connecting

Symptoms:

• Devices show as “Disconnected”
• No files syncing

Diagnostics:

# Check Syncthing logs
# Docker:
docker logs syncthing

# Native:
journalctl -u syncthing@$USER.service -f

Common fixes:

1. Firewall blocking:

# Check if ports are open
sudo netstat -tulpn | grep syncthing

# Open required ports
sudo ufw allow 22000/tcp
sudo ufw allow 22000/udp
sudo ufw allow 21027/udp

2. Wrong device ID:

• Verify device IDs match exactly
• Check for typos when manually entering IDs

3. Network issues:

• Ensure both devices have internet (if using global discovery)
• Try manual connection: Actions → Advanced → Manual Connection → tcp://device-ip:22000

4. Enable relay temporarily:

Settings → Connections → Enable Relay (to test connectivity)

Issue 2: Sync Conflicts

Symptoms:

• Files with .sync-conflict- suffix appear
• Duplicate files created

Cause: Same file modified on multiple devices before sync completes.

Resolution:

Manual review:

# Find conflict files
find /opt/syncthing/data -name "*sync-conflict*"

# Review conflicts manually
diff original.txt original.sync-conflict-20251216-123456.txt

Automated resolution:

#!/bin/bash
# Keep newest file, delete conflicts

find /opt/syncthing/data -name "*sync-conflict*" | while read file; do
    original="${file%.sync-conflict*}"
    if [ -f "$original" ]; then
        # Compare modification times
        if [ "$original" -nt "$file" ]; then
            echo "Keeping original: $original"
            rm "$file"
        else
            echo "Keeping conflict: $file"
            mv "$file" "$original"
        fi
    fi
done

Prevention:

1. Use Send Only for source of truth
2. Avoid simultaneous edits on multiple devices
3. Enable versioning to preserve both versions

Issue 3: High CPU or Memory Usage

Diagnostics:

# Check resource usage
docker stats syncthing

# Or native:
top -p $(pgrep syncthing)

Common causes:

1. Large file sets:

Syncthing scans all files periodically. Increase rescan interval:

Folder settings → Advanced → Rescan Interval → 3600 (1 hour)

2. Many small files:

Consider combining into archives or reducing watched folders.

3. Database optimization:

# Compact database (reduces size)
# Stop Syncthing first
docker stop syncthing

# Run compact (Docker example)
docker run --rm   -v /opt/syncthing/config:/var/syncthing/config   syncthing/syncthing   -home /var/syncthing/config   -no-browser   -database-tuning auto

docker start syncthing

Issue 4: Out of Sync Errors

Symptoms:

• Folder shows “Out of Sync” status
• Files not updating

Diagnostics:

1. Click on the out-of-sync folder
2. Check error messages
3. Review “Out of Sync Items” list

Common fixes:

Permission errors:

# Fix permissions
chown -R 1000:1000 /opt/syncthing/data
chmod -R 755 /opt/syncthing/data

Filesystem issues:

# Check for file system errors
sudo fsck /dev/sdX

# Check disk space
df -h

Force rescan:

1. Go to folder
2. Click Actions → Rescan
3. Or: Actions → Override Changes (forces re-sync)

Issue 5: Slow Sync Speeds

Diagnostics:

Check connection type in web UI (device details).

Optimizations:

1. Use direct connections:

Ensure port forwarding configured (22000 TCP/UDP).

2. Increase block size:

Folder → Advanced → Block Pull Order → Increase block size

3. Disable compression:

For fast local networks or already-compressed files:

Folder → Advanced → Compression → Never

4. Check bandwidth limits:

Settings → Connections → Remove download/upload rate limits

5. Network-specific:

# Increase TCP buffer sizes (Linux)
sudo sysctl -w net.core.rmem_max=16777216
sudo sysctl -w net.core.wmem_max=16777216
sudo sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216"
sudo sysctl -w net.ipv4.tcp_wmem="4096 65536 16777216"

---

11. Monitoring and Maintenance

Health Monitoring

Check sync status:

# Using Syncthing API
curl -X GET -H "X-API-Key: your-api-key"   http://localhost:8384/rest/system/status | jq

# Check folder status
curl -X GET -H "X-API-Key: your-api-key"   http://localhost:8384/rest/db/status?folder=default | jq

Monitoring script:

#!/bin/bash
# /opt/scripts/syncthing-health.sh

API_KEY="your-api-key"
API_URL="http://localhost:8384"

# Get system status
status=$(curl -s -H "X-API-Key: $API_KEY" "$API_URL/rest/system/status")

# Parse with jq
uptime=$(echo "$status" | jq -r '.uptime')
connections=$(echo "$status" | jq -r '.connectionServiceStatus')

echo "Syncthing Health Check"
echo "Uptime: $uptime seconds"
echo "Connection Status: $connections"

# Check folder sync status
folders=$(curl -s -H "X-API-Key: $API_KEY" "$API_URL/rest/system/config" | jq -r '.folders[].id')

for folder in $folders; do
    sync_status=$(curl -s -H "X-API-Key: $API_KEY" "$API_URL/rest/db/status?folder=$folder" | jq -r '.state')
    echo "Folder $folder: $sync_status"
done

Update Management

Docker updates:

# Pull latest image
docker-compose pull syncthing

# Recreate container
docker-compose up -d syncthing

# Verify
docker logs syncthing

Native installation updates:

# Ubuntu/Debian
sudo apt update
sudo apt upgrade syncthing

# Verify version
syncthing --version

Log Rotation

For Docker:

# In docker-compose.yml
services:
  syncthing:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

For native installations:

# Create logrotate config
sudo nano /etc/logrotate.d/syncthing

Add:

/home/*/.config/syncthing/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}

---

12. Advanced Topics

Custom Discovery Servers

Host your own discovery server for privacy.

Deploy stdiscosrv:

services:
  stdiscosrv:
    image: syncthing/stdiscosrv
    container_name: syncthing-discovery
    restart: unless-stopped
    ports:
      - "8443:8443"
    volumes:
      - ./stdiscosrv-data:/var/stdiscosrv
    command: -listen="0.0.0.0:8443"

Configure clients:

<!-- In config.xml -->
<options>
    <globalAnnounceServer>https://your-discovery.example.com:8443</globalAnnounceServer>
</options>

Syncthing Relay Server

Host your own relay for improved privacy and performance.

# Install strelaysrv
docker run -d   --name syncthing-relay   -p 22067:22067   syncthing/relaysrv   -listen="0.0.0.0:22067"

Use custom relay:

Settings → Connections → Sync Protocol Listen Addresses:

relay://your-relay.example.com:22067

Integration with Home Assistant

Monitor Syncthing status in Home Assistant.

configuration.yaml:

sensor:
  - platform: rest
    name: Syncthing Status
    resource: http://192.168.1.100:8384/rest/system/status
    headers:
      X-API-Key: your-api-key
    value_template: '{{ value_json.uptime }}'
    json_attributes:
      - myID
      - connectionServiceStatus
    scan_interval: 60

  - platform: rest
    name: Syncthing Folder Status
    resource: http://192.168.1.100:8384/rest/db/status?folder=default
    headers:
      X-API-Key: your-api-key
    value_template: '{{ value_json.state }}'
    scan_interval: 60

---

Conclusion

You now have a comprehensive understanding of Syncthing for decentralized file synchronization in your homelab.

Key Takeaways:

1. Privacy-First: Your data stays on your devices, no cloud intermediaries
2. Flexible: Works across platforms, customizable for any workflow
3. Reliable: Built-in versioning, conflict resolution, and error handling
4. Scalable: Handles everything from phone photos to massive media libraries
5. Secure: End-to-end encryption, device authentication, granular access control

Your Next Steps:

• Start with simple two-device sync to learn the basics
• Expand to multi-device setups as you gain confidence
• Integrate with backup solutions for data protection
• Explore advanced features like custom relay/discovery servers
• Join the Syncthing community for support and inspiration

Related Guides:

• Restic + Backrest: Modern Backup Strategy for Homelabs
• Borg Backup + Vorta: Efficient Homelab Backups
• MinIO: Self-Hosted S3-Compatible Object Storage

Welcome to the world of decentralized, privacy-respecting file synchronization!

---

Guide Version: 1.0 Last Updated: December 2025 Estimated Read Time: 30-40 minutes Estimated Implementation Time: 40 minutes initial setup + customization time

Created for homelabbing.io - AI-Forward Homelab Resource Platform