You copy a one-line address on your laptop. You need it on a phone that is using mobile data. The useful question is not whether both devices can ping each other. The useful question is whether the devices can establish a trusted data session, choose a working route, and deliver the content without making the desktop wait.
Syzygy treats those as separate jobs. The account service authorizes a pair. The devices exchange history metadata. The transport chooses a path.
The scheduler decides what can run in the background. The receiver writes the result to its local history. The interface reports each state. That separation gives you a useful explanation when a sync takes longer than a network ping.
The trust boundary
Syzygy starts with an account and a local node. The account identifies the user and the device membership. The node owns the working copy on that device. Pairing adds another node to the trusted set.
The pair does not grant every device access to every account action. The server applies role and entitlement rules before it accepts the pair. The device then proves the identity that the pair authorized. The transport carries encrypted frames after that proof.
The relay can forward those frames. The relay cannot read the clipboard payload. The server does not become a daily clipboard proxy. This boundary matters when you pair a personal laptop with a work phone.
You can remove the phone from the trusted set. The laptop keeps its local history. The phone loses the ability to request future data. The revocation decision belongs to the account and pairing layer.
It does not depend on the last route that the devices used.
Pair a device
Open Devices on the device that already contains your history. Choose Add device. Keep the confirmation view open. Open Pair on the second device.
Confirm the displayed device identity on both screens. Give the device a name that you will recognize later. Review the sync mode before accepting. Accept the pair.
The new node starts with a small control exchange. The control exchange includes membership and capability information. The devices then compare recent history headers. The first catch-up does not need to copy every blob.
The header tells the receiver which items exist. The receiver can show a pending row before it owns the full content. This lets you finish pairing without waiting for a project archive to cross the network.
What a header contains
A header identifies a history item. It can include the item identifier. It can include the creation time. It can include the content family.
It can include the title and filename. It can include tag names and tag colors. It can include preview metadata. It can include the size of the content blob.
It does not need to contain every byte of a large file. The receiver stores the header in its local read model. The list can then sort and filter the item. The preview can explain that the content is pending.
The tag editor can work on header metadata. The Download action can request the blob when you need it. This is why a synced item can appear before its image or PDF arrives. The row represents a known item.
The pending state describes the missing local content. The two facts belong together.
Realtime and on-demand
Realtime mode favors small recent items. The runtime uses the configured prefetch policy. Items inside the effective threshold can materialize in the background. Items above the threshold keep their header and remain pending.
On-demand mode keeps blob transfer behind an explicit Download action. This is useful when a phone uses a metered plan. It is useful when a laptop contains a large design export. It is useful when you want to inspect the list before copying files.
The mode controls automatic materialization. It does not prevent header synchronization. It does not prevent tag updates. It does not prevent search over metadata that has arrived.
It does not make an incomplete item look complete. The pending badge remains visible until the local blob is ready.
Large projects need background work
A project folder can contain thousands of files. The history item may represent a collection with a large aggregate size. Opening the Quick Panel should not wait for that collection. The transfer worker owns the download.
The foreground surface reads progress from the shared runtime state. The clipboard action keeps its own priority. Pressing Enter on a ready item can copy it while another item downloads. The scheduler limits work instead of blocking the command surface.
The desktop shows bytes received and the current rate when those values exist. The desktop shows pending when it has only the header. The desktop shows syncing when a worker owns the task. The desktop shows ready after local persistence completes.
The interface does not label a queued item as ready. That distinction keeps an action safe to press.
Finding a route
The transport gathers candidate addresses from the available interfaces. One candidate can belong to the local network. Another can belong to a Tailscale interface. Another can be a public address discovered through the node runtime.
The runtime can also receive a relay endpoint. A candidate is an option. It is not the selected route. The probe checks whether the peer can answer on that path.
The connection layer records the local and remote address that won. The diagnostic view calls the result direct when the peers exchange frames without a relay hop. The view calls the result relay when a relay carries the encrypted session. The view can show a direct route over a VPN interface.
The label describes the transport outcome. It does not guess from the address prefix.
LAN, Tailscale, and relay
LAN traffic often has the smallest round-trip time. The runtime can prefer it when the probe succeeds. Tailscale can provide a direct encrypted path across different networks. The address may look remote even when the packet avoids a relay.
The mobile carrier can place the phone behind a NAT. The home router can place the laptop behind another NAT. The nodes try the available traversal methods. When direct exchange fails, the relay gives the pair another path.
The relay keeps the session alive while the nodes remain authenticated. The fallback does not require a new pairing. The route can change after a network transition. The connection layer validates the new path before using it for data.
The device can move from Wi-Fi to mobile data without changing its account identity. The diagnostic record shows the route that carried the operation.
Direct does not mean local
Users often read direct as LAN. The two labels answer different questions. LAN describes an interface or address context. Direct describes the session path.
A Tailscale address can carry a direct session. A public address can carry a direct session. A relay can be the best route when both peers sit behind restrictive NATs. The device card exposes the selected remote address.
It exposes the selected local address. It exposes the route label. The detailed diagnostic view adds probe and transfer timing. Use those fields when you report a slow sync.
Do not report a route from the candidate list as if it had carried data.
Connection reuse
Creating a new transport session for every item wastes the handshake. Syzygy keeps a healthy peer connection available for more than one operation. The first operation pays for discovery and handshake. Later operations can reuse the established connection.
The diagnostic view records whether reuse happened. The scheduler still checks that the connection is alive. An idle or failed session leaves the reusable pool. The next operation can create a replacement.
The queue does not mark a failed connection as success. The retry path records the failed attempt. This makes a reconnect visible instead of hiding it inside an unexplained delay.
Why a 100 ms ping can become a four-second sync
Ping measures a small network exchange. Sync includes more stages. Discovery can wait for a peer announcement. A probe can time out before another candidate answers.
A connection can require a handshake. The scheduler can wait behind another transfer. The receiver can write a large blob to local storage. The read model can refresh after persistence.
The UI can render the new state on the next event turn. The diagnostic timeline separates these intervals. Look for queue wait when the route RTT remains low. Look for connect retries when the selected route changes.
Look for receive or persistence time when the remote side answers quickly. Look for UI refresh time when the local database already contains the item. The total is a sum of work, not a second name for RTT.
Transfer stages
The sender creates a sync intent. The intent identifies the peer and item. The queue applies the current policy. The worker obtains or reuses a connection.
The sender transmits the header. The receiver validates the header. The receiver writes the header projection. The worker checks whether the blob fits automatic policy.
The worker requests blob bytes when policy allows. The receiver writes chunks to local storage. The receiver verifies the completed content. The receiver updates the history projection.
The event stream informs the desktop. The desktop refreshes the visible row. The item reaches ready after the local content check. Each stage can report an error.
The user can act on the stage instead of guessing.
Scheduling keeps commands usable
The global sync scheduler allows up to three concurrent sync jobs. Each peer receives one active job at a time. The per-peer limit prevents one device from monopolizing the queue. Automatic transfers share a byte budget.
The default automatic budget is 64 MiB. The budget protects a mobile device from an unexpected backlog. Manual Download expresses a stronger user intent. The queue persists that intent before starting the worker.
The worker can then resume after a restart. The foreground command does not own the transfer lifetime. Closing the Quick Panel does not cancel a download by accident. Opening the panel again reads the same task state.
This ownership rule keeps keyboard actions responsive during catch-up.
Retry and timeout behavior
Control messages use a bounded retry schedule. The current delays are 0, 250, and 900 milliseconds. The schedule handles a short packet loss without adding a long pause. Blob connections use a five-second connect timeout.
The worker allows up to six attempts for a blob connection. Each attempt records its outcome. The queue stops retrying after the bounded budget. The item remains pending or failed with a visible reason.
The UI offers retry when the operation can run again. The runtime avoids an unbounded retry loop. An unbounded loop would hide a broken route and consume mobile data. The diagnostic view lets support compare timeout count with route changes.
What a pending item lets you do
You can open the item row. You can inspect its content family. You can see its title and preview metadata. You can add or remove a tag.
You can move it to Trash. You can restore it when the row is in Trash. You can ask the worker to Download. You cannot copy bytes that do not exist locally.
The action menu reports that prerequisite. The item does not pretend that a remote preview is a local clipboard payload. This matters for a remote image inside an HTML capture. The browser can display the image.
The node still needs to materialize bytes before a system clipboard write.
Mobile data and battery
A phone has a different cost model from a workstation. Automatic materialization should respect the selected threshold. On-demand mode keeps large blobs behind a tap. Header synchronization uses small messages.
The device can show new text without fetching a video or archive. The scheduler limits parallel work. The connection can remain ready for another control exchange. The UI shows the selected route and current transfer state.
The user can stop a manual download when the cost changes. The item remains pending until the local content is complete. The next attempt can resume from the persisted task state.
Tags and deletion across peers
Tags belong to item metadata. A tag update can travel with the header path. The receiving device persists the tag color it received. The Tags page and item chip read the same stored color.
Trash state also belongs to the synchronized item projection. Restore creates a visible state transition. Delete forever removes the local item from history and search. The peer receives the deletion event when the sync policy allows it.
The blob transfer does not decide whether the item is active. This keeps organization usable while content remains pending.
A slow sync diagnosis
Open Devices. Find the peer card. Read the route summary. Check whether the route says direct or relay.
Copy the selected remote and local addresses. Open the detailed network diagnostic dialog. Check the last probe time. Check connection reuse.
Check handshake duration. Check queue wait. Check bytes sent and received. Check acknowledgment time.
Check persistence time. Check retry count. Check the final state. A route with a stable 100 ms RTT and a long queue wait needs scheduler investigation.
A route with repeated five-second connects needs network or candidate investigation. A ready database row with a late UI update needs a read-model investigation. The same total duration can have different causes. The timeline tells you which one occurred.
Diagnostic privacy
The diagnostic copy action removes account secrets. It should not include clipboard text. It should not include blob contents. It can include a peer identifier suitable for support correlation.
It can include route labels. It can include IP addresses when you choose raw diagnostic mode. Review that mode before sharing it outside your team. The summary mode keeps the route class and timing fields.
The full mode helps a network administrator compare NAT behavior. Both modes explain the capture time. Support can match a report to the retry and connection timeline. You keep control of the data you paste into a ticket.
Network transitions
A phone can leave Wi-Fi while a download is running. The old path may stop responding. The runtime detects the failed exchange. The connection layer validates an available path.
The worker keeps the same sync intent. The queue does not create a duplicate item. The item remains syncing while the replacement path starts. The diagnostic record shows the transition.
The final state reports ready or failed. If the peer disappears, the task remains retryable. If the content was only a header, the header remains usable. This behavior turns a network transition into a recoverable state change.
Pairing removal
Open the paired device list. Select the device. Review the last-seen state. Choose Remove or Revoke.
Confirm the identity. The account service records the change. The other node loses future authorization. Existing local history stays on each device.
Removing a pair does not erase local clipboard data. Use the local Trash and retention controls when you want deletion. Use device removal when you want to stop trust. Those actions solve different problems.
A laptop to phone workflow
Pair the phone from Devices. Choose on-demand mode on the phone. Copy a short address on the laptop. Wait for the phone header to appear.
Open the pending row on the phone. Tap Download. Watch the selected route. Watch bytes received.
Open the preview after the row reaches ready. Press Copy. The laptop remains available for another task. The phone does not download the rest of the laptop history.
The user intent controls the expensive step.
A design file workflow
Copy an SVG from a design tool. The sender stores its semantic source when available. The receiver gets the header first. The preview can show the graphic state.
The source view can remain available after the blob arrives. Use the source when you need editable text. Use the rendered image when you need a visual copy. The capability depends on the local content representation.
A pending header cannot provide local source bytes. The download action completes that prerequisite. The history keeps the original item separate from any edited snapshot.
A remote image workflow
An HTML capture can contain an image URL. The header can arrive before the image bytes. The preview surface can display a remote resource when policy allows it. The system clipboard still needs a local materialized image.
Pressing Enter cannot bypass that requirement. The UI reports the missing materialization state. The worker follows the request and response limits. The worker validates the URL scheme.
The worker follows redirects inside the allowed boundary. The worker stores a complete result before injecting it. The operation either produces a valid local payload or leaves the clipboard unchanged. This protects a quick paste from partial remote data.
Common failure: pairing succeeds, headers do not arrive
Check that both nodes are running. Check the peer last-seen time. Open the diagnostic view. Check for discovery timeout entries.
Check whether a connection was reused. Check whether the selected route changed between attempts. Confirm that the account still lists both devices. Retry the control exchange.
If the route remains unavailable, inspect the VPN or carrier NAT. Share summary diagnostics with support. Do not share clipboard contents as a workaround.
Common failure: headers arrive, blob stays pending
Read the sync mode. Read the item size. Compare the size with the automatic threshold. On-demand mode expects a manual Download.
Realtime mode can leave a large item pending. Press Download once. Watch for a queued state. Check the byte budget.
Check the peer concurrency limit. Check the final error reason. The header is not evidence that the blob failed. The pending badge tells you which action remains.
Common failure: direct route falls back to relay
Read the selected route instead of the candidate list. Check the probe error. Check whether the local interface changed. Check whether the carrier NAT expired a mapping.
Check whether the VPN allows peer traffic. The relay is a valid encrypted fallback. It may have a higher RTT. It should not trigger a new pairing.
If relay transfer succeeds, the content path works. If every route fails, share the candidate and retry timeline. The timeline gives the network administrator a place to start.
Common failure: Enter does nothing during a download
Check whether the selected item is ready. A pending item needs Download before it can write bytes. A ready item can copy while another item transfers. Check the action capability shown in the menu.
Check that the target application still has focus permission. Check the clipboard write result. Check the paste injection result when using Quick Panel mode. The foreground command should report its own error.
It should not wait for an unrelated background task. If the ready item remains blocked, capture the command diagnostic event.
FAQ
Does the server store every clipboard blob?
The product uses the server for account and pairing decisions. Trusted devices carry ordinary sync data through the P2P transport. Review your deployment and retention settings for the exact service boundary.
Does direct mean that the devices are on the same Wi-Fi?
No. Direct describes the session path. A VPN interface can carry a direct session across networks.
Why does a pending item show tags?
Tags belong to the header projection. The device can persist metadata before it receives the blob.
Can I force every item to download?
Choose a policy that fits the device and network. Manual Download remains available for a pending item. Large backlogs should run in the background.
Does removing a device delete its local history?
No. Pair removal changes authorization. Use Trash and retention controls for local deletion.
What should I send to support?
Send the copied diagnostic summary. Include the operation time and final state. Include the selected route if raw mode is safe for your report. Never include clipboard text or secret tokens.
A small verification checklist
Pair two devices. Confirm both identities. Copy a short text item. Confirm the header arrives.
Confirm the phone can copy the ready item. Copy a large file. Confirm the pending state appears when policy requires it. Press Download.
Confirm progress and transfer rate update. Switch from Wi-Fi to mobile data. Confirm the route can change. Open network diagnostics.
Confirm the selected route matches the operation. Confirm the connection reuse field changes between first and later operations. Move an item to Trash. Confirm the peer receives the metadata state.
Restore the item. Revoke the paired device. Confirm future requests fail with an authorization state. Confirm each device keeps its local history until you delete it.
Continue reading
Read clipboard content types to see why the header names a content family. Read preview, popup, and Command + K to understand the action boundary. Read indexer and OCR search to see how a downloaded image becomes searchable. Read Tags and Trash to keep metadata and deletion state organized.
P2P sync works best when the product makes trust, route, policy, and progress visible.