User Guide

1 Linux

Download covesync-linux-amd64, make it executable, and move it to your PATH:

chmod +x covesync-linux-amd64
sudo mv covesync-linux-amd64 /usr/local/bin/covesync

2 Windows

Run the CoveSync-Setup.exe installer. CoveSync will be added to your Start menu and configured to run as a Windows Service automatically.

3 macOS

Download the .dmg, open it, and drag CoveSync to Applications. On first launch, macOS may ask you to allow it in System Settings → Privacy & Security.

1 Start the daemon

On Linux, run covesync in a terminal. On Windows and macOS the service starts automatically after installation.

covesync

You'll see a line like:

CoveSync started. Web UI: http://localhost:8485

2 Open the web UI

Open http://localhost:8485 in your browser (this is the default port — you can change it in ⚙️ Settings). The web UI will load without any certificate warning.

1 Go to the Peers tab

Open the web UI on Device A and click Peers. You should see Device B listed as a discovered device within a few seconds.

2 Enter Device B's code

Click Trust on Device B's entry. A modal opens showing your own code and asking for Device B's code.

On Device B's web UI, go to Settings → Security and note the 6-digit trust code. Type it into the modal on Device A and click Establish Trust.

Device A will now show an Awaiting their trust badge next to Device B until Device B completes their side.

3 Device B enters Device A's code

On Device B, click Trust next to Device A. Enter Device A's 6-digit code (shown in Device A's Settings → Security) and click Establish Trust. Both devices now show a Trusted badge.

If Device B missed the prompt, click the Awaiting their trust badge on Device A — a dialog shows your current code so you can read it to the other person.

1 Go to Folders on Device A

Click Folders → Add Folder. Browse to the folder you want to sync, give it a label, and click Add.

2 Share with a peer

In the folder settings, click Share with peer and select Device B from the list. An invitation will appear on Device B.

1 Go to Folders on Device B

Click Folders. A pending share invitation from Device A will appear at the top. Click Accept.

2 Choose a local path

Browse to where you want the folder to sync on Device B. You can create a new folder here if needed. Click Confirm.

CoveSync will begin syncing immediately. The first sync downloads all existing files from Device A.

1 Install and open the app

Install CoveSync from the Google Play Store. Open the app — it will begin discovering devices on your network automatically.

2 Trust your PC

Your PC should appear in the app's Peers list. Tap it, verify the fingerprint matches your PC's web UI → Settings fingerprint, then tap Trust.

Accept the incoming trust request on your PC's web UI.

3 Share a folder to Android

On your PC's web UI, go to a synced folder → Share with peer → select your Android device. Accept the share invitation in the Android app and choose a local folder.

1 Linux — systemd user service

covesync systemd-install
systemctl --user enable --now covesync

CoveSync will start automatically when you log in, without requiring root.

2 macOS — launchd

covesync launchd-install

This installs a LaunchAgent that starts CoveSync at login.

3 Windows

The Windows installer configures CoveSync as a Windows Service automatically. No extra steps needed.

📂 Double-click to open a file

Files whose extension is in the openable list (images, PDFs, documents, audio, video, and more) show a pointer cursor. Double-click one to open it in the default application on your computer — just like double-clicking in your file manager.

To customise which extensions are openable, go to ⚙️ Settings → File Browser, edit the comma-separated list, and click Save.

🔍 Filter the history

Type any text into the Filter box and press Enter (or click Filter) to search across file paths and peer names. The pager updates to show only matching events. Click Clear to go back to the full log.

1 Copy some text

Copy text to your clipboard as you normally would (Ctrl+C / Cmd+C).

2 Select a peer and click Send

At the top of the right column in the web UI, select a peer from the Send Clipboard dropdown and click Send.

On first use, your browser may show a permission prompt: "Allow [site] to read your clipboard?" or "Allow to paste from clipboard?" — click Allow. This only appears once. After granting, Send works with a single click.

The status line shows ↑ Sent to [peer] · HH:MM on success.

3 Receiving

The receiving peer's web UI polls for incoming content every 3 seconds. When content arrives it is written directly to the system clipboard and the status shows ↓ Received from [peer] · HH:MM.

If the tab isn't focused when content arrives, the status will say ↓ From [peer] · tap to copy — click the status line to copy manually.

📋 Default patterns

These six patterns are active out of the box:

.DS_Store
Thumbs.db
desktop.ini
*.tmp
*.temp
~$*

They cover macOS desktop metadata, Windows thumbnail and display caches, generic temp files, and Microsoft Office lock files (e.g. ~$report.docx).

✏️ Pattern syntax

Patterns use Go's filepath.Match glob syntax and are always matched case-insensitively:

• *.tmp — any filename ending in .tmp
• ~$* — any filename starting with ~$
• .DS_Store — an exact filename match
• build.log — matches build.log anywhere in the folder tree

Patterns match against the filename only, not the full path. To exclude an entire directory, move it outside the synced folder instead.

What CoveSync syncs

CoveSync syncs file content and last-modified timestamps only. The following are silently dropped:

• Extended attributes — macOS Finder tags, resource forks, and xattrs; Linux xattrs; Windows Alternate Data Streams (ADS)
• Symlinks — symbolic links are skipped entirely. Only the real files they point to (if inside the folder) are synced.
• File permissions — UNIX mode bits, ownership, and ACLs are not preserved.

macOS aliases and Windows .lnk shortcuts are regular data files from the filesystem's perspective and are synced, though they may not resolve correctly if the target path differs on the receiving device.

Windows filename restrictions

Windows prohibits certain filenames that are valid on Linux and macOS:

• Names containing a colon — e.g. meeting: notes.txt
• Names ending in a space or period — e.g. draft or file.
• Reserved device names — CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9

Files with these names will silently fail to sync on Windows peers. The error is recorded in the daemon log (look for WARN pull) but is not shown as a UI error. The file remains intact on all non-Windows devices.

Recommendation: avoid these naming conventions in any folder shared with Windows peers.

Case sensitivity (Linux ↔ macOS / Windows)

Linux filesystems are case-sensitive — Readme.txt and readme.txt are two distinct files. macOS and Windows treat them as the same file.

If a Linux host contains two files whose names differ only in case, both are synced, but on a macOS or Windows peer they will collide — the second to arrive overwrites the first with no warning.

Recommendation: do not use same-name-different-case files in folders shared with macOS or Windows peers.

Files locked by another process (Windows)

On Linux and macOS CoveSync can read files that are open by another application. On Windows, exclusively-locked files (e.g. a .pst archive open in Outlook) cannot be read — CoveSync skips them silently and retries on the next sync cycle. A WARN cannot hash line appears in the daemon log.

Microsoft Office lock files (~$*.docx, etc.) are excluded by the default sync filter and are never transferred.