Skip to main content

Adding Devices and Sharing Folders

This is the core operational workflow in Syncthing. Every sync relationship is made of two things: a trusted Device pair and a shared Folder pair.

Learning Focus

Understand that Syncthing requires both sides to explicitly approve a device before any data flows. Syncthing never syncs to an unknown device.

The Pairing Model​

sequenceDiagram
  participant A as Node A (VPS)
  participant B as Node B (Laptop)
  A->>B: I trust Device ID B-K3X2R...
  B->>A: I trust Device ID A-M9PQT...
  A<<->>B: Mutual trust established — sync can begin

This is a mutual handshake. If only one side adds the other, no connection is made.

Step 1: Get Each Device's ID​

On each node's GUI, go to Actions → Show ID.

The Device ID looks like:

K3X2R2T-6VBHVQB-GQLK6XO-AVNQDQE-YBNFYAR-TWAXSJC-6FXMPWE-YEP5ZAQ

Copy it — you'll need to enter it on the other device.

Step 2: Add a Remote Device​

On Node A (VPS):

  1. Click + Add Remote Device (bottom-right of the GUI).
  2. Paste Node B's Device ID into the "Device ID" field.
  3. Set a Device Name (e.g., my-laptop) — this is just a label for you.
  4. Click Save.

Node A now shows the device as "Disconnected" until Node B approves it.

On Node B (Laptop):

Syncthing will pop up a notification: "New Device: K3X... Would you like to add it?"

  1. Click Add Device.
  2. Confirm the Device Name.
  3. Click Save.

Both nodes now show each other as "Connected".

warning

If no notification appears on Node B, verify both nodes can reach each other (LAN/internet/relay). Check that global discovery is enabled on both: Settings → Connections → Enable Global Discovery.

Step 3: Share a Folder​

Sharing a folder is also a mutual two-step process.

On Node A: Add and Share the Folder​

  1. Click + Add Folder (Folders panel, left column).
  2. Fill in the General tab:
    • Folder Label: A human-readable name (e.g., "Website Uploads").
    • Folder ID: A unique machine-readable ID (e.g., uploads-prod). This must match exactly on both sides.
    • Folder Path: The local directory on this node (e.g., /var/www/html/uploads).
  3. Go to the Sharing tab:
    • Check the box next to Node B (Laptop).
  4. Click Save.

On Node B: Accept the Folder​

A notification appears: "Node A (VPS) wants to share 'uploads-prod'. Accept?"

  1. Click Add on the notification.
  2. Set the local Folder Path for this device (e.g., /home/user/uploads).
  3. Click Save.

Syncthing now scans both folders, computes differences, and begins syncing.

The Folder ID​

The Folder ID is the most critical matching field. Both devices must use the identical Folder ID for a folder pair to link up.

Label (GUI only)Folder ID (must match)
Node AWebsite Uploadsuploads-prod
Node BMy Uploadsuploads-prod

If the IDs don't match, the relationship never forms.

Understanding the Sync Flow​

flowchart LR
  A_DISK[Node A\n/var/www/html/uploads] -->|scan + index| A_IDX[(Node A Index)]
  B_DISK[Node B\n/home/user/uploads] -->|scan + index| B_IDX[(Node B Index)]
  A_IDX <-->|compare indexes via BEP| B_IDX
  B_IDX -->|pull missing blocks| A_DISK
  A_IDX -->|pull missing blocks| B_DISK
  1. Each node scans its local folder and indexes file metadata.
  2. Nodes exchange indexes over BEP (Block Exchange Protocol).
  3. Each node determines what it's missing and pulls those blocks directly from the peer.

Hands-On Practice​

# On Node A (create a test file)
mkdir -p ~/sync-lab
echo "Hello from Node A — $(date)" > ~/sync-lab/hello.txt

# In the GUI: Add Folder → Folder Path = ~/sync-lab → Folder ID = sync-lab-test
# Share with Node B, and accept on Node B

# On Node B (verify)
cat ~/sync-lab/hello.txt
# Expected: Hello from Node A — <timestamp>

Common Mistakes​

MistakeWhat happensFix
Mismatched Folder IDsFolder never links, stays as separate foldersEnsure both sides use identical Folder IDs
Only one side adds the otherDevice shows as "Disconnected" foreverBoth sides must add each other
Folder path doesn't existSyncthing errors on saveCreate the directory first

What's Next​