What exactly gets synced?

Supported content rows sync separately from files. Beta.40 adds appliance-side downloads of missing note images and background renditions; voice audio uses a separate download path. These downloads do not currently verify manifest checksums.

The health endpoint shows mediaMissing — is data lost?

Not necessarily. Check connectivity, credentials, peer version, disk space, and source-file availability. Missing files can be downloaded on eligible pull cycles, but a persistent count does not prove permanent loss.

Do deletes propagate?

Fully for notes, documents, folders, and voice recordings. For bookmarks, collections, highlights, conversations, and pinned tags, deletes are best-effort — delete on the other instance too.

Cloud Sync and Media Transfer

Pair your appliance with your cloud account, sync supported rows, and download missing media.

7:00 intermediate Sep 17, 2026

Video coming soon.

Before you start

self-hosting/01-deploying-with-docker
self-hosting/03-configuration-and-multi-device

What you'll learn

Pair the appliance with your cloud account using a sync token
Understand which content types and files sync, and how conflicts resolve
Read the sync health signal and recover missing media
Run multiple appliances against one cloud account

Reference documentation

Read the technical docs for this feature →

Cloud Sync exchanges supported rows between two Glassy instances — an appliance and its cloud account, or an appliance and a private receiving instance in a Zero Reliance Pair. The sending appliance also downloads missing note images and background renditions referenced by local rows. Voice audio uses a separate download path. These downloads are not two-way file replication.

Pairing the appliance

Generate a sync token on the receiving instance

On the instance you are syncing to — app.glassy.fyi, clear.glassy.fyi, or your own VPS in a Pair — open Settings → Cloud Sync and click Generate. The raw token is shown only once. It is separate from the self-host membership token and can be rotated independently.

Save the pairing on the sending appliance

On the appliance, open Settings → Cloud Sync, paste the token into Pair token, enter the receiving instance’s URL in Syncs to, and choose Save Cloud Sync settings. The token is stored encrypted and both values are resolved every cycle, so no restart is needed.

For a scripted/bootstrap install only, GLASSY_SYNC_TOKEN in .env remains the recovery path and is read at boot.

Verify and run a first cycle

In the appliance’s web app, Settings → Cloud Sync shows the peer connection, credentialSource, pending outbound count, and per-type cursors. Click Sync now for an immediate cycle. With the default 10-second fast check, local writes typically reach the peer within seconds.

What syncs, and which direction

Per-type toggles and the conflict policy (most-recent last-writer-wins by default, or cloud-wins) live in Settings → Cloud Sync on each side. Direction (push-only / pull-only / two-way) belongs to the sending appliance, which runs the cycles. Disabled types pause in the outbox — held, not lost — and flow again when re-enabled.

Media transfer (beta.40+)

After row sync, the appliance downloads missing note images and custom-background renditions referenced by local rows. Voice audio uses its own endpoint. The server exposes a manifest with hashes, but the current downloader does not consume it or verify checksums. This is appliance-side download, not two-way file replication. If the peer is offline, a later eligible cycle can retry.

Reading the health signal

The Cloud Sync panel and /api/sync-token/health report files missing from this instance. The current mediaMissing counters cover voice audio and note images; they do not certify every asset class or prove the source has lost a file.

On eligible pull cycles, the appliance attempts to download missing files from the peer. If a count persists, check connectivity, credentials, peer version, disk space, and source-file availability. A persistent count alone does not prove permanent loss.