Skip to main content

Shared folder

If your team already has a shared drive, that is all the infrastructure you need. DeepState writes encrypted change files into a folder and reads what others wrote. It doesn't matter how the folder is shared - SMB, OneDrive, Dropbox, Google Drive, Syncthing, a USB stick walked between rooms - because nothing in it is readable without the board key.

Setting up​

The person sharing: Collaborate → Shared folder → Share via folder… → choose an empty folder on the shared location. DeepState writes the header and the current history into it immediately. Copy the invite code and give it, plus the folder location, to your colleagues.

Everyone else: Join shared board… → paste the code → Shared folder → pick the same folder. The board is rebuilt from the folder on the spot.

How it works​

Inside the folder:

header.json              plaintext: format version, board ID, key fingerprint
ops/<device-id>.ndjson   one file per device, append-only, each line an encrypted batch of changes
blobs/<file>.dse         encrypted media, one per image / video / document
  • Each device only ever writes its own ops/ file, appending to the end. There is nothing to lock and no way for two writers to clobber each other, which is what makes this safe on file sync services that would otherwise produce "conflicted copy" files.
  • Each device remembers how far it has read in every other device's file and reads only the new bytes.
  • Media is uploaded when the folder lacks it and downloaded when the device lacks it.
  • If a device holds changes authored elsewhere that the author never wrote to this folder (say the author only uses the relay), the device relays them on so the folder stays complete.

Timing​

The folder is checked every 15 seconds, plus immediately when the operating system reports a change in it (this works on local and SMB shares; cloud-sync clients sometimes don't signal, so the 15-second poll covers them), plus about 2 seconds after you make a local change. Sync now in the Collaborate dialog forces a pass. On cloud services add their own upload/download latency: typically seconds for Dropbox and OneDrive, up to a minute or two for Google Drive.

Status​

The Collaborate dialog shows the folder path, when it last synced, counts of pushed and pulled changes and files, and any error (folder unreachable, permission denied). Pause stops both reading and writing; Resume picks up where it left off.

Sneakernet​

For air-gapped environments, put the folder on a USB stick. Each machine syncs when the stick is plugged in; because every device only appends to its own file, carrying the stick in any order between any number of machines converges correctly. Combine with changes files for one-off transfers by email.

Housekeeping​

  • The ops/ files grow forever. Compacting history on your device does not shrink files already written to the folder; to reclaim space, stop sharing, delete the folder's contents, and share again into the empty folder (which writes the compacted history).
  • Do not edit or delete files in the folder by hand while devices are using it. Deleting a device's ops/ file makes every other device forget how far it had read and re-apply from the start, which is harmless but slow.
  • Moving the folder: stop sharing on every device, move it, share/join again from the new path.

Security notes​

Everything except header.json is encrypted with the board key; the header contains only the board ID and a hash of the key. Anyone who can read the folder can see that a board exists, its ID, how many devices write to it and how active each is - but not a byte of content. Anyone who can write to the folder could delete or corrupt files (denial of service) but cannot forge changes, because the authenticated encryption rejects anything not made with the key.