Checkpoint: From Two Authorized Devices to One Shared Model
Syncthing's identity and discovery layers solve different halves of the same setup problem: one device must know which peer it is speaking to, and it must find a route to that peer. This checkpoint connects those ideas with the folder and model relationship that follows a successful connection. The useful judgment is diagnostic: when two machines fail to synchronize, can we tell whether the problem is trust, reachability, folder authorization, or the absence of a shared description of file state?
One shared folder is a chain, not a handshake
Consider a laptop and a home server that a user wants to keep aligned. The relationship begins before either machine sends a file. Each machine generates and retains its own cryptographic identity. The user adds the other machine's device ID to the local configuration, creating a mutual expectation about which certificate should appear at connection time. This is the first boundary: the devices are known to one another as cryptographic peers rather than as names in a contact list.
The user then selects a folder to share. That action is narrower than adding a device. A server can be an authorized peer without being authorized for every folder on the laptop. Conversely, a folder can be configured for a peer while a different folder remains private or follows another policy. The distinction prevents a successful device connection from becoming a blanket permission to exchange all local data.
When Syncthing starts, it creates or loads its configuration and keys, starts the administrative interface, initializes listeners and discovery, and scans the configured folders. The connection service gathers candidate addresses from static configuration or discovery. A local announcement might reveal a route on the same network. A global lookup might return an external address. A relay might provide the only practical path through two NATs. These routes answer where to try, not whether the result is the intended peer.
The connection then returns to the identity boundary. The TLS handshake presents certificates; each side derives the peer's device ID; the configured allowlist and certificate-name expectations are checked; and the devices exchange Hello information. If the certificate does not match the expected identity, the route has failed as a trust path even if packets travelled successfully. If the peer is unknown, Syncthing may learn enough about it to show a pending device, but it does not turn that observation into folder access.
Only after those decisions does folder sharing become meaningful on the connection. The devices exchange cluster configuration describing the folders relevant to the relationship. A folder that is not shared, is paused, or is unknown on one side is not a synchronized folder merely because the devices are connected. The distinction is easiest to preserve by asking four separate questions in order:
- Is this the device the user intended?
- Is there a usable route to it?
- Is this particular folder shared across the relationship?
- What does each side believe the shared folder contains?
The fourth question changes the nature of the system.