Your First Sync

Two paired devices still share nothing. A folder is what gets shared — and, like the pairing, it is created on each device separately, with the same folder ID on both.

Building a folder from the template

Rather than inventing a folder description, the lab starts from Syncthing's own defaults, served by the API:

$ curl -s -X GET -H "X-API-Key: $KEY" http://127.0.0.1:8385/rest/config/defaults/folder
{
  "type": "sendreceive",
  "rescanIntervalS": 3600,
  "fsWatcherEnabled": true,
  "ignorePerms": false
}

Four facts about a fresh folder, worth having before you change any of them: its type is sendreceive (chapter 8 is about the other types), it rescans the whole folder every 3600 seconds as a backstop, a filesystem watcher notices changes as they happen (so the hourly rescan is rarely what finds them), and file permissions are not synced.

The lab shapes that template into a complete folder — id gazette, label "Gazette drafts", a different local path on each device, both device IDs listed — and installs it on both:

{
  "id": "gazette",
  "label": "Gazette drafts",
  "path": "/home/hatch/workspace/syncthing-lab/share-a",
  "type": "sendreceive",
  "devices": [
    "VDKRCPU",
    "PJCM4SS"
  ]
}

$ curl -s -X PUT -H "X-API-Key: $KEY" http://127.0.0.1:8385/rest/config/folders/gazette -d @folder-a.json
[HTTP 200]

The ID must match on both devices; the label and the path are each device's own business. That separation — same folder, different folder on disk — is the whole trick of sharing between a Linux laptop and a Windows desktop without arguing about paths.

Files appear

Into willow's empty folder go the newsletter team's files: the issue draft, the masthead, an events list, and a photos subfolder with its captions. On juniper, with nothing typed there at all:

$ sha256sum share-a/issue-12-draft.md share-b/issue-12-draft.md
1335a664e52f6f2adc613b7a5cc19a97a84ff8810f03209fcf1e50362a0002b9  share-a/issue-12-draft.md
1335a664e52f6f2adc613b7a5cc19a97a84ff8810f03209fcf1e50362a0002b9  share-b/issue-12-draft.md

Identical hashes, and the masthead matches the same way. This is the only proof of sync worth trusting: not a progress bar, not a green tick, but the same bytes under the same name on a machine that never saw you type.

Juniper's folder also gained something willow didn't send:

$ ls -a share-b
.
..
.stfolder
events-list.txt
issue-12-draft.md
masthead.txt
photos

The .stfolder directory is a marker Syncthing creates in every folder it manages. It is the folder's proof to itself that this directory is really the shared one — if the marker goes missing (an unmounted drive, a half-restored backup), Syncthing stops rather than inventing an empty folder and "syncing" that emptiness everywhere. Remember it exists; chapter 10 comes back to it.

What "in sync" looks like

A folder that has settled describes itself, on juniper:

$ curl -s -X GET -H "X-API-Key: $KEY" "http://127.0.0.1:8395/rest/db/status?folder=gazette"
{
  "state": "idle",
  "needFiles": 0,
  "needBytes": 0,
  "localFiles": 4,
  "globalFiles": 4
}

Learn this shape; the whole guide uses it as the instrument panel. state idle — not syncing, not scanning. needFiles 0, needBytes 0 — nothing this device knows it is missing. localFiles 4, globalFiles 4 — what I have matches what the folder's shared truth says exists: four files (the captions inside photos/ count; directories themselves do not). When those numbers disagree, something specific is wrong, and the later chapters read them like gauges — the folder-type chapter (chapter 8) runs on nothing else.

Check: on your own two devices, the same status call should settle to idle with local and global counts equal, and a file's sha256sum should be the same string in both places. If the counts are equal but a hash differs, you do not have a sync problem — you have two different files wearing one name, which is chapter 7.