HivemindOS manual

Hivemind Sync and Tailscale

Hivemind Sync is how the shared brain and handoff files move between your machines. Tailscale, or the app-managed Hivemind Link, is the private network those machines use to reach each other.

The shared brain is a normal markdown folder. Obsidian is the editor, not the transport. HivemindOS reads and writes the vault folder, and one sync owner you choose moves the files between machines.

Where the shared brain lives

The default vault path is ~/Documents/Obsidian/hivemindos-vault. HivemindOS can also find common Obsidian locations, or you can set NEXT_PUBLIC_OBSIDIAN_VAULT_PATH.

The vault holds agent inboxes, handoffs, Kanban state, notifications, scheduled-run files, shared skills, and shared context.

If the vault is unavailable, some features fall back to local app storage. For example, Kanban falls back to ~/.hivemindos/kanban. That keeps the dashboard usable, but other machines and agents won’t see that state until the vault is reachable and syncing again.

Choose one sync owner

In Brain, the Sync owner setting decides who moves vault files between machines. Pick exactly one. Two sync tools managing the same vault may work for a while, then get confusing, because each has its own conflict format, timing, and retry behavior.

External provider

Choose this when Obsidian Sync, iCloud Drive, Dropbox, Git, your own Syncthing, or another folder sync tool already owns the vault. HivemindOS reads and writes the local folder and leaves replication to that tool. It doesn’t pair Syncthing, but you can still run a manual repair.

This is the safest choice if you already use Obsidian Sync or keep the vault in another synced folder.

HivemindOS Syncthing

Choose this when you want HivemindOS to set up syncing for you. It pairs Syncthing on your machines through their collectors:

The dashboard finds your Tailscale peers.
Each peer with a ready collector reports that it supports Syncthing, along with a default sync path.
The local and remote collectors exchange Syncthing device IDs.
Both collectors add the hivemindos-vault folder and add each other as peers.
Syncthing keeps the files in sync over your private Tailnet.

Auto-pairing runs only when the shared brain is on, Sync owner is HivemindOS Syncthing, auto-pairing is turned on, the vault path is set, and the remote collector reports Syncthing support.

HivemindOS doesn’t implement its own realtime sync engine. It sets up Syncthing, gives each side a private peer address such as tcp://100.x.y.z:22000 (or dynamic discovery), and lets Syncthing do the continuous replication.

Manual repair only

Choose this when realtime sync is off or handled elsewhere, but you still want a one-shot repair between trusted machines. Dry run and Sync now use rsync over Tailscale SSH to push, pull, or reconcile both ways. Tailscale SSH must work from the dashboard machine to the target.

Conflicts

Syncthing conflicts belong to Syncthing. They appear as Syncthing conflict files in the vault and in the Syncthing UI. HivemindOS doesn’t rename or merge them.
Manual repair conflicts belong to HivemindOS. In a two-way repair it compares local, remote, and last-known hashes. If both sides changed a file since the last repair, the remote copy is kept beside yours as a file like note.conflict-host-2026-05-23T00-32-00-000Z.md. After a successful repair, HivemindOS saves the new baseline in ~/.hivemindos/vault-sync/.

What Tailscale is used for

Tailscale gives your machines a private network. HivemindOS uses it for separate jobs that share the same Tailnet but not the same protocol:

Fleet discovery and collector access
Hivemind Link app-managed collector access
Syncthing peer addresses
Shared env pulls, with SSH as a fallback
Vault repair and fleet update fallback over Tailscale SSH

The collector should stay private to your Tailnet. HivemindOS doesn’t need Tailscale Funnel.

Hivemind Link

Hivemind Link is the default. It lets Fleet and remote chat work without installing the system Tailscale VPN client. A small sidecar joins your own Tailscale account as a HivemindOS app node.

In Link mode:

The collector listens only on 127.0.0.1.
The sidecar listens on the Tailnet and forwards to the local collector.
The dashboard sends requests for remote collectors to the local sidecar, which reaches the peer through its embedded Tailscale connection.
Prompts, responses, model lists, and collector calls still travel over Tailscale’s WireGuard-encrypted links.

Link carries only HivemindOS app traffic. It doesn’t replace system Tailscale for Tailscale SSH, rsync repair, or Syncthing peer addresses. Run ./setup.sh --system-tailscale when you need those.

For Link URL shapes and troubleshooting, see Fleet telemetry and Hivemind Link.

Tailscale SSH

Some actions need to run a command on a trusted peer. They use Tailscale SSH instead of public SSH:

hive-env-add --pull-from pulls env keys from a trusted peer.
Vault repair runs rsync.
Fleet update fallback runs update commands on a remote machine.
Remote folder browsing can fall back to a shell listing when a collector is out of date.

On macOS, the App Store (sandboxed) Tailscale app can join the Tailnet and carry collector and Syncthing traffic, but it can’t host the Tailscale SSH server. A Mac that must receive Tailscale SSH commands needs a Tailscale build with the tailscaled daemon, such as the Homebrew or open-source daemon. Linux uses the normal service.

Handoff transfers

To send files, images, reports, or generated artifacts from one agent to another, use the hive-transfer helper. It puts a handoff in the vault addressed to a specific machine, runtime, or agent, with payload hashes and an acknowledgement from the receiver. See Hivemind Sync handoff transfers.

Local-only mode

Tailscale is optional. Without it, HivemindOS runs as a local dashboard with a local vault. Cross-machine discovery, collector access, HivemindOS Syncthing pairing, shared env movement, and rsync repair stay off until the machine joins a Tailnet.

Safety

Secrets don’t belong in the vault. Shared env values move through the hive env helpers and ready collectors, and peer pulls can use Tailscale SSH.
Keep collectors reachable only on trusted private networks. Use Tailnet ACLs if you need stricter separation between dashboard machines and agent machines.