Skip to content

What Syncthing Is

Syncthing answers a small question completely: how do these machines keep this folder the same, without anybody else's computer being involved?

Most sync tools are really storage tools. You upload your files to a company's server; your other machines download them from there. The server is the hub, the account is your identity, and the free tier is the business model.

Syncthing has no hub. Each machine runs the program, each pair of machines connects directly — over your home network, or the internet if you let it find a way — and the machines exchange the folder's contents between themselves. If every Syncthing server on earth vanished tonight, your two laptops would still sync tomorrow, because there are no Syncthing servers in your setup at all. (There is infrastructure you may use — discovery servers that help machines find each other, relays that carry traffic when no direct path exists — but they are optional helpers, they never hold your files, and this guide's lab switches them off.)

The four ideas

Everything else in this guide is these four ideas working themselves out.

A device is a key pair. When Syncthing first runs on a machine it generates a private key and a certificate, and from them a device ID — a long string like VDKRCPU-UXHNS6G-4QRZCAS-…. That ID is the device's name and its proof of identity in one: the ID is derived from the certificate, so a machine cannot claim an ID without holding the matching private key. There is no username, no password, no registration. Chapter 2 generates two of them.

A folder is the unit of sharing. You point Syncthing at a directory and give it a folder ID (gazette, in the lab). Other devices see the folder ID and the list of files; the actual path on disk — /home/you/newsletter here, D:\Gazette there — is local business and is never shared.

Files travel as blocks. A changed file is not re-sent whole. Syncthing cuts files into blocks, hashes them, and asks: which blocks does the other side already have? Only the missing blocks cross the wire. That is why appending a paragraph to a large file is cheap, and it is why the guide proves syncs with sha256sum — when the hashes match, the files are the same, whatever route the blocks took.

Every change is equal. Creating, editing, and deleting are all just new states of the folder, announced to every device sharing it. There is no special ceremony for a delete, and that one fact explains both the elegance and the sharp edges: chapters 4, 6, and 7 are all chapter-and-verse on what "a delete is just a change" really costs and buys.

The lab

The guide's lab runs two complete Syncthing instances on one machine, as two fictional volunteers editing a community newsletter:

  • willow (device A) — GUI and API on 127.0.0.1:8385, sync listener on 127.0.0.1:22005
  • juniper (device B) — GUI and API on 127.0.0.1:8395, sync listener on 127.0.0.1:22006

One machine, two homes, two folders on disk, talking over loopback. Everything a real two-laptop setup does with its sync engine, this does — minus the internet, which the lab deliberately removes (discovery, relays, and NAT traversal all off) so that every capture shows the engine, not the network.

$ ./bin/syncthing --version
syncthing v1.27.2-ds4 "Gold Grasshopper" (go1.22.2 linux-amd64) debian@debian 2025-07-21 04:55:34 UTC

That is the standard Linux build of Syncthing v1.27.2 (the distribution package; the lab runs the binary from it directly). Versions matter in this guide wherever behaviour is version-shaped, and the criteria page says which claims are pinned to this one.

Check: on your own machine, syncthing generate --home=some-new-folder will print a device ID of your own (chapter 2 walks through it). If the string you get looks like the ones above — eight groups of letters and digits — you are holding the same thing the lab is built from: an identity that nobody issued you and nobody can take away.