HivemindOS manual

Hivemind Sync Handoff Transfers

Handoff transfers send files from one machine or agent to another through your shared vault. Only the machine, runtime, or agent you target sees them. Use them for screenshots, generated media, reports, and source bundles.

Don’t send secrets this way. Transfers are stored in the synced vault, so every device paired to it may receive a copy.

How it works

The sender creates a transfer. It lands in a hidden .hivemindos-transfers/ folder in the vault, with a manifest listing the target, a note, and each file’s size and SHA-256 checksum.
Your vault sync copies it to the other machines.
The receiver checks its inbox and sees only transfers addressed to it.
After using the files, the receiver acknowledges the transfer, and it leaves that receiver’s inbox.

If the receiver is offline, the transfer waits until sync and inbox checks resume.

Send with `hive-handoff`

Setup installs hive-handoff. It finds the target machine from a rough name and picks the best agent there for the job.

# Send a file
hive-handoff send --to <machine> ./screenshot.png

# Send a file with instructions for an agent
hive-handoff send --to <machine> --task "edit this image and save a web-ready version" ./screenshot.png

# Send only a task
hive-handoff task --to <machine> "summarize the local project state"

# Preview the chosen machine and agent without sending anything
hive-handoff plan --to <machine> --task "..."

In dashboard chat, /handoff-task <machine> <task> sends a task the same way.

Agents should ask what the receiving agent should do before sending a task handoff. A plain file handoff doesn’t need that question.

Send with `hive-transfer`

hive-transfer is the lower-level command underneath hive-handoff. Use it when you know the exact target.

hive-transfer send --toMachine <machine-id> --toRuntime hermes --toAgent <agent-id> \
  --note "source screenshot for preview QA" ./screenshot.png ./report.md

hive-transfer inbox --machine <machine-id> --runtime hermes --agent <agent-id>

hive-transfer ack <transfer-id> --machine <machine-id> --runtime hermes --agent <agent-id>

Use --toHost <hostname> instead of --toMachine if the receiver has no machine ID yet.
Add --all to inbox to include transfers you already acknowledged.
Use --syncPath <vault> for a vault that isn’t in the default location.

inbox returns JSON with local paths to the files once sync has delivered them.

Who sees a transfer

Target field	Effect
Machine ID (`to.machineId`)	The receiving machine. Preferred, because hostnames can change or collide.
Host (`to.host`)	Fallback when there’s no machine ID yet. Must match exactly.
Runtime (`to.runtime`)	Optional. Limits it to one runtime, such as `hermes`, `openclaw`, or `aeon`.
Agent (`to.agentId`)	Optional. Limits it to one agent in that runtime.

A wrong machine, runtime, or agent never sees the transfer. An inbox checked at runtime level (no --agent) sees every transfer for that runtime, so a supervisor can route work inside it. To limit a transfer to one agent, set to.agentId and have that agent check with --agent.

HTTP API

A machine’s collector serves the same inbox when its /health reports capabilities.fileTransfers: true. Keep collectors private to your Tailnet or Hivemind Link; never expose them on the public internet.

Request	Purpose
`GET /transfers?machineId=&host=&runtime=&agentId=&all=true`	List the inbox. All parameters are optional.
`POST /transfers`	Create a transfer. Body: `files` (absolute paths), `note`, `from`, `to`.
`POST /transfers/ack`	Acknowledge. Body: `id`, `machineId`, `runtime`, `agentId`.

The dashboard also offers a higher-level planner at POST /api/handoff, with body fields action, target, files, task, and note:

Action	What it does
`plan`	Picks the machine and agent without doing anything.
`send-file`	Sends a plain file transfer.
`send-task`	Starts a task on the best agent on the target machine.
`send-file-task`	Sends files and starts a task that collects them.
`spawn-subagent`	Starts a fresh isolated agent and returns a job ID right away.
`check-subagent`	Reads the job’s status without waiting.
`await-subagent`	Waits for the job’s result.
`run-subagent`	Spawns and waits in one call.

MCP tools

Setup installs hivemind-mcp, a local MCP server for runtimes that prefer tools to shell commands. HivemindOS must be running for it to work.

Handoff: list_hivemind_machines, plan_handoff, handoff_file, handoff_file_task, handoff_task.
Subagents: spawn_subagent, check_subagent, await_subagent, run_subagent.
Crypto and payments: crypto_capabilities, select_crypto_rail, prepare_crypto_action. These choose or prepare a payment rail but never spend on their own.

About subagents:

spawn_subagent returns a job ID right away. check_subagent never waits; await_subagent does.
Each child runs in a new session. It doesn’t see the parent’s conversation, and only its final answer comes back, capped by responseBudgetChars (1,000–12,000 characters, default 6,000).
Pass agent to pick a specific agent. HivemindOS avoids choosing the calling agent when another is available.
Children can run on HivemindOS, Hermes, Codex, Claude Code, OpenCode, OpenHands, Aider, Claw, or OpenClaw, if that runtime is ready on its machine.
A task waits up to 20 minutes. Put longer work on the Work Board.
Clients that support MCP 2025-11-25 tasks can run run_subagent as a background task and poll tasks/get for the result.

Troubleshooting

The receiver sees nothing. Check that both machines use the same vault and that the transfer folder has synced to the receiver. Compare the manifest’s to fields with the receiver’s machine ID, host, runtime, and agent.

Sync says connected but files don’t arrive. In Syncthing, a peer can be connected but not sharing the vault folder. Add the missing device to the vault folder on the peer, rescan, and test with a small file.

The wrong agent sees a transfer. It’s probably checking at runtime level. Set to.agentId and have agents check with --agent.

You’re unsure a file arrived intact. Compare it with the sha256 and bytes values in the manifest before acknowledging.

Hivemind Sync
Shared Env, for keys and other secrets
Slash Commands