I have been building a Windows client that presents Syncthing folders as placeholders in Explorer and fetches a file’s content when something opens it. It is a separate BEP node, not a wrapper around syncthing.exe — on the other side stands an unmodified Syncthing v2.
I am posting it here because the request keeps coming up in this forum (the Selective download and placeholder files thread is ten years old by now), and because the parts I am least sure about are the parts this audience will spot fastest.
What it does
- Placeholders through the Windows Cloud Filter API — the mechanism OneDrive uses. The files stay ordinary files: no container, no virtual drive, no FUSE. Whatever the client mounts, any other program can read at the same time.
- Cache limit per volume, eviction by last access.
- A mode per file and per folder, kept in the index: placeholder or always local. A folder passes its mode down and overrides the entries beneath it.
- Both directions. It accepts shares and offers its own folders: Index and IndexUpdate go out, inbound connections are accepted.
- Local and global discovery, one connection per device carrying all of that device’s folders, index in SQLite with resumption after a restart.
- Conflicts follow Syncthing’s naming; replaced and deleted revisions go under
.stversions, retention configurable. - Thumbnails on demand: when the file manager asks for an image, the client fetches one 128 KiB block and cuts out the embedded EXIF preview. The placeholder stays a placeholder.
What it never does
It never announces content it does not hold. FileInfo.setLocalFlags() calls setNoContent(), which discards the block list and the size, so a Syncthing device announces only what it actually has — and the client does the same. Peers therefore never request blocks it cannot serve, and its completion figure stays honest. The price is that Syncthing shows the client at a low percentage permanently. That is correct, not a defect.
Discarding content is the dangerous operation, so it is the one hedged most
Content is never dropped because a cache is full. It is dropped only once the file has been proven recoverable, and every one of these has to hold:
- enough peers carry it in full — the count is configurable per share, minimum 1, so the last copy in the network cannot disappear;
- they carry this version — compared by version vector, not by timestamp. A timestamp says which change happened later, not whether one side knew about the other;
- their announcement matches this content — block list and size, recomputed locally. The name proves nothing: a peer may hold a different file under the same name;
- the announcement is old enough — BEP never tells a sender that the receiver has finished, and a peer echoes our own announcement, block list included, long before it fetches a byte. Treating that echo as proof of possession would delete the file before it arrived anywhere;
- the file is not pinned, not always local, not open, not locally modified.
A peer that merely knows the file does not count: its index entry has to carry a block list and a size greater than zero. The honest-announcement rule above is what makes that count mean anything.
Empty files are the one exception — zero bytes can never reach the threshold, because the count demands blocks. Such a file is released when it is empty here and empty on the peer, judged by its own size rather than the announced one.
Limits, plainly
- Windows 10 version 2004 (build 19041) x64 or newer. The Cloud Filter API is Windows-only, so that will not change.
- Version 0.9.x. In daily use here against Syncthing v2 across three devices, but it is one person’s code and it is young.
- Its own TLS layer, because Windows does not support Ed25519.
- The installer is unsigned — SmartScreen will warn. SHA-256 checksums are on every release.
- One known open issue: two paths deliver content for always local — the Cloud Filter hydration and the background fetch — and when they meet, Windows reports a lock on the file.
- No warranty of any kind, and I mean that as written. Never run it without an independent, verified backup, and never as the only place data lives.
- The repository is read-only apart from me. Bug reports through issues are welcome; patches will not be merged. One source for changes, deliberately.
Apache-2.0, sources, changelog and releases: GitHub - Taloan/SyncTClient: Windows Syncthing Client with advanced Placeholder/OnDemand and dedicated FolderSync selection (as OneDrive, Nextcloud) features · GitHub