🖥️ Desktop Applet

Continuous cross-platform sync. Automatically mirror and back up your file histories across Mac and Windows directly to your personal server.

Overview

The Companion Desktop Applet is a lightweight background process that runs on your Mac or Windows machine and maintains a continuous, bidirectional sync between your local file system and your Companion Hub. It acts as the persistent bridge between your everyday computing and your personal server, ensuring that files, documents, and activity traces flow into Digital Memory automatically.

The applet lives in your system tray and operates silently in the background. You interact with it only when you need to — configuration, status checks, or triggering a manual sync.

Key Features

Automatic file sync — monitors configured folders and syncs changes to your Hub in real time
File versioning — keeps a configurable number of historical versions of every file
Selective sync — include/exclude patterns, folder rules, and file type filters
Activity capture — optionally logs app usage, window focus history, and clipboard events to Digital Memory
Bandwidth throttling — configurable upload/download limits to prevent saturation of your network
Conflict resolution — handles simultaneous edits on multiple machines with smart merge rules
Offline queue — queues changes when Hub is unreachable and syncs automatically on reconnect
Encrypted transfer — all data is encrypted in transit over the Hub’s local network

Supported Platforms

Platform	Status
macOS 12+ (Intel & Apple Silicon)	✅ Available
Windows 10/11 (x64)	✅ Available
Linux (experimental)	🔄 In progress

Use Cases

Automatic off-site backup to your own hardware, not a cloud provider
Sync your Documents, Desktop, and Downloads folders across multiple machines via your Hub
Feed your entire file activity history into Digital Memory for searchable recall
Replace iCloud Drive or OneDrive with a self-hosted equivalent
Keep a versioned history of every document you’ve ever worked on

Architecture


Mac / Windows Machine
├── Applet (tray icon)
│   ├── File Watcher (FSEvents / ReadDirectoryChangesW)
│   ├── Activity Monitor (optional)
│   └── Sync Engine
│             │  delta sync over Hub API
│             ▼
         Hub (hub.ci.localhost)
              │
              ├──▶  File Storage (NAS / local disk)
              └──▶  Digital Memory Server (activity events)

Changes are detected via native OS file system events, delta-encoded, and uploaded. The applet never holds a full copy of the remote file tree in memory.

Setup

Download and install

Download the applet installer from your Hub dashboard under Apps → Desktop Applet, or directly from:

macOS: https://get.ci.computer/applet/mac
Windows: https://get.ci.computer/applet/windows

Run the installer and follow the prompts.

Pair with your Hub

On first launch, the applet pairing wizard opens. Enter your Hub address (default http://hub.ci.localhost) and the pairing code shown in Hub → Settings → Devices → Pair New Device.

Configure sync folders

In Applet Settings → Sync Folders, click Add Folder and select the directories you want to sync. Common choices:

~/Documents
~/Desktop
~/Downloads
Your project directories

Set optional activity capture

Navigate to Applet Settings → Activity and choose which activity types to capture:

File events (recommended)
App focus (records which apps you use and for how long)
Clipboard (captures copied text for memory search — disable if sensitive)

Usage

Checking Sync Status

The system tray icon shows the current sync state:

Green — synced and idle
Blue (spinning) — actively syncing
Yellow — paused or throttled
Red — error (click to see details)

Pausing Sync

Right-click the tray icon → Pause Sync → select a duration (15 min, 1 hour, until I resume).

Browsing File History

In the applet window, navigate to File History to browse versioned snapshots of any synced file. Click a version to restore it or export a copy.

Triggering a Manual Sync


# macOS / Linux
ci-applet sync --now
 
# Or right-click the tray icon → Sync Now

Accessing Synced Files from Another Machine

Synced files are accessible on any machine running the applet paired to the same Hub, or via the Hub’s File Browser web interface at http://files.ci.localhost.

Troubleshooting

Applet not connecting to Hub Verify your Hub is running and your machine is on the same network. If Hub is remote, ensure the Portal is configured for remote access. Check the applet log at Settings → Logs.

Sync stuck in “Uploading” A large file transfer may be in progress. Check Settings → Bandwidth to see current transfer rates. If stuck permanently, pause and resume sync. If the problem persists, check the Hub’s storage availability.

Conflict files appearing Conflicts occur when the same file is modified on two devices before syncing. Open the Conflicts view in the applet, review both versions, and choose which to keep.

High CPU usage If you have a folder with thousands of small files, the initial scan can be CPU-intensive. This normalizes after the initial sync. Exclude high-churn directories (e.g. node_modules, .git) using the folder exclusion rules in Settings.

File missing after Hub storage migration Re-run a full sync from Settings → Advanced → Force Full Sync.