Syncthing for Mere Mortals
Syncthing keeps a folder the same on two or more machines. Edit a file on one and the edit appears on the other. There is no account to sign up for, no company's server holding your files, and no monthly tier: the machines talk to each other directly, prove who they are with cryptography, and get on with it.
That "no server in the middle" is the whole idea, and it cuts both ways. It is why Syncthing is private and free in a way the cloud drives are not. It is also why some behaviours surprise people raised on Dropbox: a delete is not a move to a recycle bin, it is an instruction every other machine obeys; if two machines edit the same file while apart, there is no referee to ask — Syncthing keeps both versions and leaves the judging to you.
Every behaviour in this guide was run for real, in a lab of two Syncthing instances on one machine — Syncthing v1.27.2, the standard Linux build — talking over loopback addresses with discovery, relays, and NAT traversal switched off, so what you see is the sync engine itself and nothing else: files created, edited, and deleted on one side and checked by hash on the other; an ignore pattern proven by the file that didn't arrive; a deleted file recovered from the versions folder; a genuine sync conflict, manufactured on purpose.
What this guide covers
- What Syncthing is — the model: devices, folders, blocks, and identity made from a key pair instead of an account
- Two devices, paired — generating an identity, reading the config it writes, quietening a fresh install, and introducing two devices by ID
- Your first sync — a folder shared both ways, the folder marker, and what "in sync" looks like in numbers
- Edits and deletes are just changes — an edit propagating, and the delete that propagates exactly the same way — because to Syncthing there is no difference
- Choosing what travels —
.stignore, the patterns file that is not itself synced, and sharing patterns with an include file that is - Versioning, the safety net — the trash-can versioner catching replaced and deleted files on the receiving side, and putting one back
- When both sides edit — the sync conflict: which version wins, which is kept, and the name that tells you it happened
- Folder types — send-only and receive-only folders, local changes that go nowhere, and throwing them away on purpose
- The REST API — everything the web GUI shows is an API call; pairing, status, ignores, pause and resume with curl, plus the built-in command line client
- When sync goes wrong — the symptom list: the file that never arrived, the edit that came back, the folder that will not settle, and what each one actually means
What it doesn't cover
Finding your machines across the internet — global discovery, relay servers, and NAT traversal are real parts of Syncthing, and the lab switches them all off on purpose so the engine can be watched in isolation; they are named, and their off-switches shown, but their behaviour is documented-only here. The phone and desktop apps, and working in the web GUI beyond proving it exists, are likewise out of scope: everything in this guide is done through the API the GUI itself uses. Other versioning modes than the trash can, encrypted folders for untrusted devices, and running Syncthing as a system service are named where they belong and left to the official documentation.
How to use this guide
Read chapters 1–4 in order; they build the
model (identity without accounts, a delete as
an ordinary change) that the rest of the guide
leans on. After that, chapters stand alone —
go to the one named after your problem. The
fixtures are in examples/, the command
sequence is collected in
examples/commands.txt, and every capture in
every chapter names the instance it came from:
in Syncthing, which device did something is
always half the story.
Part of the series
This guide is one of the For Mere Mortals guides: plain-language guides to the tools programmers and makers use.
Related guides:
License
The writing in this guide is licensed under CC BY 4.0. Code examples and lab scripts are licensed under the MIT License.