Syncthing Is a Trust-and-Reconciliation System, Not a Shared Drive
Syncthing is a continuous file synchronization program for keeping files aligned across two or more computers. This series focuses on the specific problem that appears once those computers are independent: how can they converge on useful file state without making a central service the unquestioned owner of the data, and without allowing an accidental write or an uninvited peer to undermine the result? The practical value of the answer is a mental model. Instead of treating Syncthing as a magical shared folder, we can see which question each layer answers, what it protects, and where its protection stops.
The real problem is not moving files
A file-copy tool can ask a simple question: which bytes should be copied from here to there? Continuous synchronization has to ask more difficult questions first. Is the other computer an authorized participant? Can the two devices reach one another today, even if their addresses changed? If both devices changed the same path while disconnected, are the changes ordered, concurrent, or based on one another? Which parts of a large file actually differ? Are the bytes received from a peer the bytes the desired file describes? Has the local file changed while a remote replacement was being prepared?
Syncthing's own priorities make clear why these questions cannot be treated as secondary engineering details. Its goals put safety from data loss first and security against attackers second, ahead of ease of use, automation, and performance. The project explicitly says that it may refuse an unsafe trade-off for the sake of speed or convenience. It also distinguishes security from anonymity: protecting file data from unauthorized access is a goal, but hiding the fact that a machine runs Syncthing is not currently the system's promise.
That priority order explains several behaviors that can otherwise look fussy. A failed transfer is not supposed to leave a half-written destination posing as the current file. A peer is not trusted merely because it answered at a discovered address. A simultaneous edit is not quietly erased just because one version has a later-looking timestamp. The system is willing to preserve a conflict, delay a change, or ask for an explicit policy choice when guessing would put the user's data at risk.
Consider what happens when the laptop and server in the example are not simply taking turns. The laptop may edit a document while the server is disconnected; the server may edit another file, or even the same file, before it reconnects. There is no universally reliable “latest computer” from which to copy. A clock can be wrong or reflect editing at different times, and a central service would solve some ordering problems only by becoming another authority that must store, protect, and remain available for the data. Syncthing instead lets the devices exchange enough identity and file-state information to make a bounded decision at each peer.
That choice changes the meaning of convenience. A central service can make a folder look simple because it hides location, membership, and state decisions behind one account. Syncthing exposes more of the relationship: devices are added to one another, folders are shared deliberately, and the cluster's view is assembled from participating machines. The payoff is direct control and flexible topology. The cost is that the system must handle missing peers, competing edits, and uneven filesystem behavior without assuming that one server can settle every question. Its safety mechanisms are the price of remaining a peer-to-peer system for individuals.
A useful way to read Syncthing is therefore to follow five questions through one hypothetical change. Imagine a document edited on a laptop while a second computer is offline. When the second computer returns, Syncthing needs to establish the following chain:
The chain is more important than any single component. Identity without reachability leaves a safe but disconnected device. Reachability without identity creates a path to the wrong machine. A secure connection without a model of file versions cannot tell which content is wanted. A correct model without block verification can still accept corrupted data. Verified blocks without conservative replacement can still overwrite a local change. And a converged folder without recovery history may be difficult to repair after a human mistake.
Devices, folders, and the shared state they pursue
Syncthing's vocabulary gives each part of this problem a distinct place. A device is a computer participating in synchronization. A folder is a configured set of files that may be shared with selected devices. A cluster is the group of devices and their shared relationships. The names shown in a user interface are not the authority: a device name is cosmetic, while sharing depends on explicit device identity and folder configuration.
The distinction matters in a simple two-computer setup. Suppose a laptop and a home server both run Syncthing. Adding the server as a peer does not automatically give it every folder on the laptop. The devices must be configured with each other's identities, and a folder must be selected for sharing. A connection can succeed while a particular folder remains unshared, paused, or otherwise outside the relationship. “The computers can talk” and “this file may be exchanged” are separate statements.
Each device also has a local view of its files. Syncthing records more than names and sizes: its synchronization model includes file metadata and the hashes of the blocks that make up file contents. The Block Exchange Protocol describes the union of those local views as a global model. In broad terms, the global model is the version of each path that the cluster currently considers the one to pursue. Every device tries to bring its local folder into agreement with that model, but the model is not a central database hosted by a third party. It is assembled from the state that participating devices announce to one another.
That distinction makes the word “global” easy to misunderstand. It does not mean that a server has permanent authority, that every device is always current, or that a missing peer can be conjured into existence. A device may be offline, paused, unable to serve a required block, or limited by the filesystem on which the folder lives. The global model is better understood as a coordination target: a structured answer to “which known file state should this device be trying to realize?” Availability and local health still determine whether it can do so now.
The model also explains why Syncthing begins with metadata rather than immediately streaming file contents. Before a device requests a block, it needs to know which file version the peer is describing, how large the file is, what kind of item it is, and which blocks belong to that version. This allows the receiver to compare what it already has with what it needs. It also creates a place to record uncertainty: a file can be known to be needed even when no currently connected peer can supply it.
One system, several boundaries
The most useful overall picture is not a list of modules but a sequence of boundaries. The identity boundary asks whether a certificate belongs to a configured device. The reachability boundary asks which address or relay can carry traffic to that device. The folder boundary asks whether the connection is authorized for a particular set of files. The model boundary describes which state should be pursued. The block boundary checks whether the content used to build that state matches the announced evidence. The filesystem boundary decides whether a completed result can safely replace what is on disk. Finally, the recovery boundary determines what evidence of an older or competing state remains available to the user.
None of these boundaries can substitute for the others. A relay can make an otherwise impossible connection possible, but it does not decide which device identity is acceptable. A cryptographically authenticated peer can still be unable to provide a needed block. A matching block hash can establish content integrity without telling Syncthing whether the user's application considers that content meaningful. A conflict copy can preserve an alternative without deciding which draft expresses the user's intent. Version history can improve recovery without turning a synchronized folder into an independent backup.
This layered design also gives a practical way to interpret failure. If a device is not found on the local network, that is primarily a reachability problem. If an address responds with the wrong certificate, it is an identity problem, even if the network route works perfectly. If peers connect but a folder is not shared, the failure belongs to configuration and authorization at the folder level. If metadata says a file is needed but no connected peer has it, the cluster has a content-availability problem. If a local edit appears while a remote version is being installed, the system has to protect the local state before it can decide how to converge.
The result is a restrained promise. Syncthing is designed to let individuals synchronize files directly between their own devices, with encrypted and authenticated device traffic, content-level checks, and explicit policies for conflicts and recovery. It is not designed to hide all network metadata, infer the semantic meaning of every file, or eliminate the need for independent backups and endpoint protection. The central question for the rest of this series is therefore not “How does Syncthing copy a folder?” It is “How does Syncthing build enough trust and evidence to change a folder safely?”
The first answer lies in identity. Before a device can be discovered, relayed, or asked for a block, Syncthing needs a practical rule for deciding which cryptographic peer is allowed to speak for the device the user configured. That rule is the subject of the next chapter.