# Syncing devices Every device holds a full replica of the workspace as CRDT documents ([Loro](https://loro.dev)). Changes merge by construction: two devices can edit the same course offline for a week and still converge without a conflict dialog. Syncing simply means exchanging updates, and any of the three channels below can carry them. A device can use all three. ## Through a server Connect the app to a self-hosted server in `Settings > Backup & sync > Server`. Browsers are always connected to the server that serves them. From then on the device pushes its changes to the server's log and pulls what other devices pushed. This happens automatically, shortly after every change and on every launch. The server never interprets your data. It stores opaque update blobs per account, plus the uploaded file bytes, and a background job folds long logs into snapshots so they never grow unbounded. See [Install a server](setup.md). ## Over the local network Two desktop apps on the same network find each other automatically and can sync directly, without a server or internet access. Open the **Sync** page from the top bar: nearby devices appear on their own, and pressing **Sync** next to one exchanges exactly the document updates and files the other one lacks. Turn on **Auto-sync with nearby devices** on that page to keep the devices in step in the background, without pressing Sync each time. A few things to know: - Direct device-to-device sync runs in the desktop and mobile shells, which host the discovery socket. A plain browser tab cannot advertise itself, so it syncs through a server or file packs instead. - Both devices must be on the same network, and the network must allow multicast. Guest and hotel networks often block it. - On iOS the system asks for the local network permission the first time. - The connection is not authenticated within your network, so sync on networks you trust. ## File packs `Settings > Backup & sync > Backup` exports the whole workspace as one `.synapse` file: courses, chapters, annotations, exercises, attempts, lexicon and the documents themselves. Importing it on any device merges it in; nothing gets overwritten and identical content is stored once. The same file serves three purposes: - a backup you can store anywhere, - a way to sync two machines that share no network, - a way to move your workspace into a fresh install. The export holds only the current state by default, which keeps the file small. Tick **Include history** to carry the full change history too (larger file), so the importing device also gets the timeline shown on the [History](features.md#history) page. ### What is inside a `.synapse` file A `.synapse` file is a plain zip, so any archive tool can open it to see what it holds. The layout is small and stable: ``` manifest.json { version, docs: [...], blobs: [...] } docs/workspace.snapshot the courses, chapters, links, lexicon and exercises, as one Loro CRDT snapshot docs/attempts.snapshot your exercise attempts and progress docs/ann:.snapshot one per annotated document: its highlights, drawings and notes blobs/ the document files themselves (PDFs, etc.), named by the hash of their content ``` The snapshots are CRDT documents, which is why importing merges rather than overwrites: two devices editing offline both fold in cleanly. Files live under `blobs/` addressed by content hash, so a document shared across courses is stored once, and re-importing the same file is free. Import detects a pack by its `manifest.json`, not its name, so a `.synapse` file renamed to `.zip` (or an older `.zip` export) still imports. ## Troubleshooting | Symptom | Likely cause | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Nearby devices stays empty | The devices are on different networks, or the router blocks multicast. Both apps must be running. | | Server sync stopped | The session expired. Reconnect in `Settings > Backup & sync > Server`. For native apps, check `CORS_ORIGINS` on the server. | | A document opens without its PDF | The file bytes have not reached this device yet. Sync once with a device that has them, or import a file pack that includes files. | | Two devices briefly show different orders | Updates are still in flight. Both settle on the same order after the next sync. |