Hivemind Sync

Hivemind Sync is the name for the cross-machine movement layer.

It is not one protocol. It is the app-level route that keeps trusted machines working from the same brain, the same shared env, and the same handoff folder without pretending those are all the same kind of data.

What It Moves

Hivemind Sync covers three surfaces:

• Shared brain files in the Obsidian vault.
• Shared env keys in ~/.hivemindos/.env.
• Handoff file transfers in .hivemindos-transfers/.

The shared brain and handoff transfers are vault data. They move when Syncthing or the selected vault sync owner moves the local vault folder.

Shared env is not vault data. It moves through the HivemindOS collector env endpoint when trusted peers are reachable. Pulls and some repair/fallback flows can still use Tailscale SSH.

Shared Brain

The brain is a normal local markdown vault:

~/Documents/Obsidian/hivemindos-vault

Hivemind Sync does not replace Obsidian Sync, iCloud Drive, Dropbox, Git, or another folder sync tool. The Brain settings pick one owner for realtime vault replication:

• external provider
• HivemindOS-managed Syncthing
• manual repair only

When HivemindOS manages it, the app pairs Syncthing through trusted collectors and lets Syncthing do the continuous file replication.

Shared Env

Shared env lives outside the vault:

~/.hivemindos/.env

Use the helper commands:

hive-env-add OPENAI_API_KEY
hive-env-remove OPENAI_API_KEY
hive-env-check OPENAI_API_KEY
hive-env-add --reconcile

--reconcile pushes the current shared env set to ready peers through collector /env endpoints. Those collector endpoints should only be reachable on trusted private machine links.

--pull-from USER@HOST still uses Tailscale SSH because it asks the remote machine to export its local shared env set and merge missing keys back onto this machine.

Handoff Transfers

Handoff transfers are for files and artifacts that need to move from one machine, runtime, or agent to another.

They live in the vault folder:

.hivemindos-transfers/

Each transfer is an envelope with a manifest, payload files, targeting metadata, hashes, and acknowledgement files. The receiver sees the transfer after the selected vault sync owner has replicated the folder locally.

Use:

hive-transfer send --toMachine MACHINE_ID ./artifact.png
hive-transfer inbox --machine MACHINE_ID
hive-transfer ack hive-transfer-...

Do not use handoff transfers for secrets. Use shared env helpers for keys.

Transport Map

The common rule is simple: keep the collector private, keep the vault sync owner singular, and keep plaintext secrets out of the vault.