Suwu

Folder Sync

Mirror a folder on the Suwu server into a folder on your own computer — one way, server to local, re-checked every few seconds. No upload, no second shell, no rsync.

Overview

Folder Sync mirrors a folder on the Suwu server into a folder on your own computer, and keeps the local copy identical to the remote one. It is the tile to reach for when a build on the server produces artifacts you want to open in a local editor — or when you want the same tree to exist on your laptop without a second shell.

Sync is one-way: server → local. The server is always the source of truth, so there is nothing to reconcile and nothing to merge. The local folder is read and written directly by your browser through the File System Access API — files are never uploaded, zipped, or staged anywhere else.

How a Sync Cycle Works

Each cycle has two phases:

  • Pre-flight — the server returns a manifest of the remote folder (paths, sizes, millisecond mtimes); the browser scans the local folder and diffs the two.
  • Sync — the plan is applied: new and changed files are downloaded, new folders are created, and (optionally) local extras are removed.

The default interval is 5 seconds, and each cycle ends in a short Watching cooldown so an unchanged tree costs almost nothing. Locally edited files are overwritten by the server copy — always logged explicitly as overwrote local change, so nothing ever disappears silently.

Setting Up a Job

  1. Open the App Menu (the grid button in the header) and add a Folder Sync app. The tile accepts two launch parameters, so you can pre-fill it from a custom app entry:
    • remotePath — the server folder to mirror.
    • interval — the cycle interval in milliseconds (default 5000).
  2. In the tile, press Add job and give it a name.
  3. Set the Server folder — pick it in the tile, or pre-fill it with remotePath.
  4. Press Choose folder and pick the destination on your computer. The browser remembers the choice, so you normally do this once per job.
  5. Leave Sync interval as-is unless you need faster or calmer syncing.
  6. Press Start. The status chip walks through Starting → Pre-flight → Syncing → Watching.

Mirror Deletions

Mirror deletions is on by default. When it is on, a file or folder that exists locally but no longer exists on the server is deleted, which is what makes "the local folder always equals the server folder" literally true. Turn it off if the local folder also holds files of your own that you want to keep.

Deletions are applied only after the downloads of that cycle succeed — if a transfer fails, the deletions are postponed rather than run against a half-synced tree.

This deletes local files

With Mirror deletions on, anything removed on the server is removed locally. Keep the local folder dedicated to the mirror rather than pointing it at a directory that holds anything you would miss.

The Sync Journal

Each synced folder carries a small .suwu-sync.json file recording what has already been pulled. It is what stops the mirror from re-downloading the whole tree every cycle, and it is how Suwu knows which side changed.

  • One folder, one server folder. If .suwu-sync.json names a different server folder, the tile refuses to start and offers Reset and start. Resetting keeps your files; the next cycle simply re-checks everything from scratch.
  • Deleting the file by hand is the way to force a full re-check without syncing first.

Activity Log

The tile keeps a running log of what each cycle did — pulled files with sizes, created folders, overwrites, deletions, skipped files, and cycle statistics such as cycle #12 · 318 checked · ↓4 · −1 · 1.2 MB · 143 ms. Use it to confirm that a build's output really arrived.

The tile toolbar has a Run one cycle now button, so you do not have to wait for the next tick while watching a build finish.

Requirements and Limits

Chromium-based browsers

Folder Sync needs the File System Access API: Chrome, Edge, or Opera, on a secure context (HTTPS or localhost). Other browsers get a clear "not supported" state in the tile. Files larger than 64 MiB are skipped and logged rather than pulled.

Also worth knowing:

  • Sync runs only while the tile is open. There is no background daemon; closing the tile stops the loop. The job configuration is kept, so reopening the tile brings the jobs back idle, waiting for Start.
  • Nothing is written to the server. The engine holds one read-only manifest endpoint; the server never learns about your local folder beyond the paths you browse.
  • Permission can be revoked. Browsers re-ask for folder access periodically. If access is denied, the tile says so and asks you to pick the folder again.