Sync a space with a folder on your Mac
Pair a folder on your own Mac directly with a space on a cloud instance. There is no local
space in between: the Memex relay app on the Mac (memex-relay) holds one outbound connection to
the instance, and each sync asks the Mac live for the folder's files. Edits go both ways, and a file
changed on both sides is kept as a conflict, never overwritten. It works while the Mac is on.
On the Mac, once
- Pair the relay with the instance as yourself, if you have not already (the same pairing the
cloud inbox uses for iMessage):
memex-relay pair https://<instance> <your user id>. The API token is read from the keyboard, never from the command line. - Share the folder:
memex-relay folders add ~/Documents/Acme. Only folders you list here can ever be reached, and the list starts empty.memex-relay folders listshows it,memex-relay folders remove <folder>takes one off. - Start the relay (or restart it after a change):
memex-relay run.memex-relay statusshows the pairing, the connection and the shared folders.
The list lives only on the Mac. The instance can neither read it nor change it.
In the space
On the space's Synchronizations page choose Folder on my Mac. The picker asks your Mac which folders it shares and lets you open their sub-folders; a folder named like the space is suggested first. The preview reads both sides through the relay and writes nothing. Start syncing creates the sync, which then runs every 15 minutes, or when you press Sync now.
If the Mac does not answer, the picker says so and offers Try again instead of a folder list.
What can and cannot be reached
- Only files inside a folder you shared. A path that climbs out (
..), an absolute path, or a folder next to the shared one that merely starts with the same name is refused by the Mac. - Hidden files and folders (
.git,.ssh,.DS_Store, anything starting with a dot) are never listed, read or written. - Symbolic links inside a shared folder are never followed, so a link cannot lead out of it. A link cannot be shared itself either, and a folder reached through one is judged by where it really is.
- Your whole disk, your whole home folder,
~/Libraryand the system folders cannot be shared at all. - The cloud asks only the Mac paired as the person who set the sync up: the relay address carries that person's id, and only their own signed-in connection can hold it. A Mac paired to someone else refuses the request.
- Someone else who edits the space cannot point your sync at their Mac, or theirs at yours: a sync that names anyone but the person who created it stops, says "This sync was set up by … but now names …", and asks nobody's Mac. To move a sync to your own Mac, use Take over with my account on it.
How it behaves
- Edits are conditional on the revision the last sync saw (size, modification time and SHA-256 of the file). A file you changed on the Mac since then is a conflict, not overwritten.
- Writes land through a hidden temporary file that is renamed into place, so an app never opens half a file. Large files cross in 256 KB pieces; a piece arriving out of order restarts the file at the next sync.
- While the Mac is asleep or off, a sync is recorded as not answering, changes nothing on either side and advances nothing. The next scheduled sync after the Mac wakes catches up.
- Deletes always name the version the last sync saw, so a file you edited since is never deleted.
- A folder the Mac may not read (macOS asks before an app reads
~/Documentsor~/Desktop) is never taken for an empty one: the sync stops, or leaves that sub-folder alone, and deletes nothing in the space. - Files over 250 MB, on either side, are listed as not synced and left where they are; everything else keeps syncing.
Not the same as "Folder on this computer"
Folder on this computer is for a mesh that itself runs on your Mac (LocalMesh). Folder on my Mac is for a space on a cloud instance; the folder stays on your Mac and the relay is the only path to it.
See the Guide for directions, the first sync and conflicts, and the design for how the relay request is checked on both ends.