Message Sync

Message Sync keeps the message history of two (or more) Meshy installations converged through a shared folder. It is useful when you use the same companion radio from two computers, for example a desktop and a laptop: messages received on one machine appear on the other after the shared folder is transferred.

Meshy never talks to a cloud service itself. It only reads and writes a folder; moving the folder between machines is left to a tool you already use, such as Syncthing (peer-to-peer) or Nextcloud, Dropbox, or Google Drive (server-based).

Enabling It

Go to Settings → Message Sync (in the left sidebar, under Backup & Restore) and turn the switch on. The dialog also shows the exact folder to point your sync tool at.

The folder is inside Meshy's own data directory, so no extra Flatpak permissions are needed:

~/.var/app/page.codeberg.sesivany.Meshy/data/meshy/sync/

For native builds: ~/.local/share/meshy/sync/.

Add this folder to your sync tool. The tool must run natively (not as a Flatpak), otherwise it cannot read Meshy's data directory. The folder holds one subfolder per companion, named after the first characters of the companion's public key, so radios with different keys never mix. Only instances connected to the same companion share a subfolder and merge each other's messages.

Within a companion subfolder each instance writes two files named after its own installation ID (<install_id><suffix>):

  • <install_id>.tail — a small append-only log that is updated after every change;
  • <install_id>.archive — a full copy of the instance's history that is rewritten only occasionally, once the tail has grown past 200 kB ("compaction").

Instances never write each other's files, so the sync tool never has to resolve a conflict. Any number of instances connected to the same companion can share a subfolder; each one merges all the others.

What Is Synced

Only messages are synced:

  • Direct messages and channel messages.
  • Read state: opening a conversation on one instance marks its messages read on the others ("read anywhere, read everywhere").
  • Deletions: removing a message on one instance removes it on the others too.

Contacts, channels, discovered nodes, routing history, radio settings, and the device identity are not synced -- those are specific to each radio and its location.

How Syncing Works

Each instance appends an encrypted record to its tail shortly after a message changes, when the radio disconnects, and periodically. Because the file is append-only, a sync tool only has to transfer the newly added part. When the tail grows past 200 kB it is folded into the archive (the full history), which keeps the frequently transferred file small.

Each record is compressed before it is encrypted, so the files are several times smaller than the raw message text. Because compression happens per record, it does not disturb the append-only layout.

On startup, whenever the folder changes, and periodically, every instance merges its peers' archive and tail. It tracks how much of each peer it has already applied, so it only reads what is new. Messages are identified by a deterministic content hash, so the same message is never duplicated no matter how many times a record is merged.

Because the merge is content-based, a peer does not need to be online at the same moment you send a message. With a server-based tool such as Nextcloud the snapshot waits on the server until the other machine connects; with Syncthing the two machines only need to be online at the same time briefly, at some point after the change.

Encryption

Snapshots are encrypted with AES-256-GCM. The key is derived (HKDF-SHA256) from the companion's private key, which any installation connected to the same radio can obtain -- so both machines derive the same key without you entering a password. The private key itself is never written to the folder or to any file on disk; only the derived key is cached locally so sync keeps working while the radio is unplugged.

Message content and the machine's name/identity are all encrypted. Only the bare minimum needed to locate and order files stays readable: the format version, a random installation ID, a generation counter, and a non-sensitive key fingerprint (so a file from a different radio is reported clearly instead of looking like corruption).

The first time you enable sync, connect the companion once so Meshy can fetch the key. If the radio is later reflashed with a new private key, the key changes and existing snapshots can no longer be read.

Warning: Do not place a backup that includes Device Identity (the private key) in the same synced or cloud folder. Anyone who obtains that file can decrypt the sync snapshots.