Clients on Deevnet FileSync

Linux

Mon, 01 Jan 0001 00:00:00 +0000

Linux Client #

Status: Draft. Phase: 1–3 (MVP). Linux is the first platform and the reference platform for the sync engine. Common client requirements are on the Clients page.

Distributions and filesystems #

LNX-1 (MVP, proposed): Fedora (the current release) is the primary, tested distribution. Other distributions are expected to work but are not tested in the MVP.
LNX-2 (MVP): Roots on ext4, btrfs, and xfs are supported.
LNX-3 (MVP, proposed): Roots on network filesystems (NFS, SMB) are allowed, but get rescan only: inotify does not report changes made by other machines. The client says so when the root is mounted.
LNX-4 (MVP, proposed): Works with SELinux in enforcing mode, without policy changes.

Agent #

LNX-5 (MVP): The background agent runs as a systemd user service, starting at login.
LNX-6 (MVP, proposed): Optional “keep running while logged out”, via systemd lingering, for always-on machines.

Change detection #

LNX-7 (MVP): inotify for live changes, plus periodic full rescans as a safety net (PERF-1).
LNX-8 (MVP, proposed): When the inotify watch limit (max_user_watches) is too low for a root, the client says so, explains the fix, and falls back to rescans. It never silently misses changes.

Keys and secrets #

LNX-9 (MVP, proposed): The device private key is protected by one of: the Secret Service (GNOME Keyring / KWallet), a TPM 2.0, or a passphrase-encrypted key file for headless machines.

Packaging #

LNX-10 (MVP, proposed): Distributed as an RPM for Fedora, plus a standalone binary tarball.
LNX-11 (Non-goal, proposed): Flatpak and Snap. Their sandboxes restrict filesystem access, which conflicts with “any folder can be a root”.

Desktop integration (Phase 4) #

LNX-12 (Phase 4): The tray app uses the StatusNotifierItem standard. On GNOME this needs the AppIndicator extension, which should be documented.
LNX-13 (Phase 4): Notifications use the freedesktop notification standard.

Open Questions #

Other distributions: is Fedora-only testing right for the MVP, or does Debian/Ubuntu also matter early?
Headless/server machines: should a machine without a desktop session (e.g. a Deevnet VM) be a supported device?

Windows

Mon, 01 Jan 0001 00:00:00 +0000

Windows Client #

Status: Draft. Phase: 4. Common client requirements are on the Clients page.

Versions and filesystems #

WIN-1 (Phase 4, proposed): Windows 11. Windows 10 reached end of support in October 2025.
WIN-2 (Phase 4): Roots on NTFS. ReFS, FAT32, and exFAT are not supported for roots.

Agent #

WIN-3 (Phase 4, proposed): The agent runs per user, started at sign-in, not as a Windows Service. A service runs as a different account, which complicates access to the user’s files and the user’s key store.

Change detection #

WIN-4 (Phase 4): ReadDirectoryChangesW for live changes, plus periodic rescans. The NTFS change journal (USN) is not used, because it needs administrator rights.

File system behavior #

WIN-5 (Phase 4): Long paths (over 260 characters) are handled whether or not the system’s long-path setting is enabled.
WIN-6 (Phase 4): Locked files. Office and other applications hold files open with exclusive locks. The client reads with shared access, retries files it cannot read, and delays applying an incoming change to a locked file. It never fails the whole sync because of one locked file.
WIN-7 (Phase 4): Incoming changes are written to a temporary file and swapped into place atomically, so applications never see a half-written file.
WIN-8 (Phase 4): Names follow the Metadata Matrix name policy: reserved names, forbidden characters, trailing dots and spaces, and case-only collisions.
WIN-9 (Phase 4, proposed): Tolerates antivirus scanning (Microsoft Defender) briefly locking newly written files.

Overlap with OneDrive #

WIN-10 (Phase 4): Windows 11 often redirects Documents, Desktop, and Pictures into OneDrive (“Known Folder Move”). The client detects a root inside a OneDrive-managed folder and warns (ROOT-8).

Keys and secrets #

WIN-11 (Phase 4, proposed): The device private key is held by the TPM (through the Windows platform crypto provider) where available, or else protected with DPAPI.

Packaging and UI #

WIN-12 (Phase 4, proposed): A per-user installer that does not need administrator rights.
WIN-13 (Phase 4): A notification-area (tray) icon and Windows toast notifications (UI-1).

Open Questions #

Code signing: unsigned binaries trigger SmartScreen warnings. Is a code-signing certificate worth buying for a personal tool, or are the warnings acceptable?

macOS

Mon, 01 Jan 0001 00:00:00 +0000

macOS Client #

Status: Draft. Phase: 5. Common client requirements are on the Clients page.

Versions and hardware #

MAC-1 (Phase 5, proposed): The two most recent major macOS releases, on Apple Silicon. Intel Macs are not supported.
MAC-2 (Phase 5): Roots on APFS. Both the default case-insensitive variant and the case-sensitive variant are supported.

Agent #

MAC-3 (Phase 5): The agent runs as a per-user launchd agent, started at login.

Change detection #

MAC-4 (Phase 5): FSEvents for live changes, plus periodic rescans.

Privacy permissions #

MAC-5 (Phase 5): macOS requires the user’s explicit consent before an app can read Desktop, Documents, Downloads, iCloud Drive, or removable and network volumes. The client asks for access when a root is mounted in one of these places, explains why, and reports clearly when access is denied rather than treating the folder as empty. An empty-looking root must never be synced as “everything was deleted”.

Overlap with iCloud #

MAC-6 (Phase 5): With “Desktop & Documents Folders” in iCloud Drive, those folders are managed by iCloud, and “Optimize Mac Storage” can replace files with placeholders. The client detects a root inside iCloud-managed storage and warns (ROOT-8). It skips placeholders rather than triggering downloads.

File system behavior #

MAC-7 (Phase 5): Names follow the Metadata Matrix name policy. In particular, NFC and NFD forms of the same name are the same file on APFS.
MAC-8 (Phase 5): Package/bundle directories are synced as directories (see the Metadata Matrix).

Keys and secrets #

MAC-9 (Phase 5, proposed): The device private key is held in the Secure Enclave where the key algorithm allows it (P-256 only), or in the Keychain otherwise.

Distribution and UI #

MAC-10 (Phase 5): A menu bar app with status, push now, pull now, and notifications (UI-1).

Open Questions #

Signing and notarization: distributing a macOS app without Gatekeeper warnings needs a paid Apple Developer membership and Apple’s notarization service. That is a dependency on Apple. For a personal tool, is building locally (or approving an unsigned app once) acceptable instead?

Android

Mon, 01 Jan 0001 00:00:00 +0000

Android Client #

Status: Draft. Phase: 6. Common client requirements are on the Clients page.

The Android client is an app built on the same Rust core, called from Kotlin.

Role: read-only access #

AND-10 (Phase 6): Android is a read-only device (a receive-only device, ROOT-9). It downloads and presents files from the hub; files never originate on, or are changed from, Android.

This removes most of what makes Android hard: