How sync and conflicts work

Sternway works fully on one device with no account. Sync is something you add later, through a sync server or a folder, and it moves the same encrypted items between devices. This page explains how a change travels, how conflicts are settled, and why a sync never quietly takes your data away.

Items and revisions

Everything you keep is an item: a host, a group, an identity, a key, a snippet, a port forwarding rule, a known host, a tag, your synced settings and so on. Each item is sealed on the device before it leaves (How the end-to-end encryption works).

When a device changes an item, it sends the new sealed version to the server together with the revision it was based on. The server keeps a revision number for each item and accepts a change only if it was made on top of the latest one. Other devices then pull what changed since they last looked.

Changes are sent right after you make them; while the app is open and unlocked, a WebSocket tells the other devices at once. Otherwise each device syncs when it starts and every minute. A device that is offline keeps its changes queued and sends them when the server can be reached; a sync that fails part-way changes nothing on the device.

When two devices change the same item

The first change to reach the server wins. When a second device sends a change based on an older revision, the server refuses it as a conflict and hands it the winning version. What the second device does then depends on the kind of item:

Kind of item	Your edit lost to another edit	Your edit lost to a deletion	Your deletion lost to an edit
Host, group, identity, snippet, port forwarding rule, workspace template	The other edit is applied, and yours is kept as a copy named “… (conflict)”	The item goes, and yours is kept as a “(conflict)” copy	The edit is kept: nothing is lost
Synced settings	The two are merged setting by setting
Key, certificate, known host, tag and the rest	The other edit is applied	The deletion is applied	Your deletion is applied on top

So for the things people edit by hand, a conflict never silently drops anyone’s work: you see both versions, keep the one you want and delete the other.

Folder sync settles conflicts with the same rules. There, two devices can both write before either has seen the other’s file; each change carries a small record of the version it was made on, so once both files have arrived every device agrees which edit came first and the losing device writes the “(conflict)” copy (Sync through a folder).

Removals are held when they are large

A pull gathers what it would remove (items deleted on another device, or no longer listed by the server) and settles it at the end:

• Connection history and session logs are applied.
• A known host the server says was deleted is always held and asked about, so a revoked or changed host key never turns quietly back into an unknown host.
• If the rest is more than 20 items, or 5 or more of one kind when that is more than half of what this device has of it, nothing is removed. Sternway writes a snapshot, holds the removals and asks, with Keep my local data as the default. Keeping them sends them back to the server, so your other devices get them again.

Smaller removals are applied without a question, as a deletion you made yourself on another device would be. The snapshot taken before the first change from the server in each run of the app, and the daily one, hold what was there.

Old versions are refused

Every item carries a version counter inside its sealed data. If the server sends an older version than the one a device has, the device does not apply it; the sync status says “The server sent an older version of N items” until a newer one arrives. A conflict whose winning copy is such an older version does not win either. This keeps a faulty or tampered server from rolling your data back.

What does not sync

Some things belong to one device and stay there: session recordings, the SSH config folder linked to ~/.ssh/config, CLI tokens, SSH agent settings, the update settings, approvals of port forwards and team host changes, device-only keyboard shortcuts, and the access keys of cloud imports. Keys and identities sync only while Settings › Security › Sync keys and identities is on; with it off, host passwords are left out of what is uploaded too. Session logs sync only with Settings › Logs › Sync session logs on.

Signing out keeps your data

Logging out of an account, deleting it, or having the device revoked never deletes your own data from the device: the personal vault stays as a local vault and the app goes on working without an account. Only the copies of team vaults leave, because access to them was the team’s to end. See How Sternway keeps your data safe.