Herd

Herd is a lightweight, zero-configuration peer-to-peer mesh clustering daemon and multi-tool CLI built in Go. It enables nodes to form decentralized, secure P2P clusters over WireGuard-powered transports with SWIM gossip membership, local Unix IPC control, distributed key-value storage, and remote execution.

Complete documentation is organized into modular guides:

• System Architecture — Daemon controller, Tailcat WireGuard data plane, and SWIM gossip layer.
• Security Deep Dive — IPC/mesh threat surfaces, transport failure modes, and agent tool risks.
• CLI & Daemon Commands — Full command reference (status, roster, join, leave, exec, forward, cp, kv, mail, agent, docs), arguments, and HERD_* environment variables.
• Actor-Style Mailbox — Asynchronous actor messaging, reactive agent loop, thread tracking, and symmetric reply routing.
• Unified Logging Architecture — Zap-backed abstract logger, subsystem namespacing, third-party adapters, and anti-pattern rules.
• Agent Quickstart — Local Ollama in minutes, herd agent status --probe, daemon/IPC notes, and troubleshooting.
• Google ADK-Go Integration — Embedded AI agent runtime, cluster tools (ClusterRoster, ClusterExec, SharedKV, AgentMail), and natural language cluster orchestration.
• Wire Protocol & Transport — Curve25519 ECDH handshake, ChaCha20-Poly1305 framing, stream multiplexing, and Tailcat DERP NAT traversal.
• Distributed Key-Value Store — Last-Write-Wins (LWW) conflict resolution, naming conventions & schemas, gossip replication, and anti-entropy push/pull sync.
• Testing & Verification — Unit test suites, integration tests, and WAN cross-device verification (Raspberry Pi 5 / macOS).
• Cross-Platform & Deployment — Multi-architecture binaries (Linux arm64/amd64, macOS Apple Silicon/Intel, Windows) and shell portability.

# Build native binary
make build

# Install to ~/.local/bin/herd
make install

# Or install from source (Go 1.21+)
go install github.com/wnoronha/herd/cmd/herd@latest

HERD_NODE_NAME=node-1 herd daemon

Check status to get the self-contained Tailcat bootstrap address:

HERD_NODE_NAME=node-1 herd status

HERD_NODE_NAME=node-2 herd daemon -join <tcpGFw...-tailcat-address-from-node-1>

# View active cluster roster
herd roster

# Write and read distributed KV data
herd kv set cluster/motd "Decentralized mesh active"
# Flags may appear after key/value: herd kv set cluster/motd "hello" --socket $HERD_SOCKET
herd kv get cluster/motd

# Send an asynchronous actor task to another node's mailbox
herd mail send --wait node-2 "Verify docker service status"

# Execute remote commands across nodes
herd exec node-2 "hostname && uptime"

# View embedded offline documentation guides
herd docs mailbox

# Local AI agent (Ollama auto-probe when no API keys — see docs/agent-quickstart.md)
ollama pull llama3.2
herd agent status --probe
herd agent prompt "List alive nodes in the cluster"

Pre-compiled static binaries are published to the GitHub Releases page:

Download and run directly without unpacking:

curl -LO https://github.com/wnoronha/herd/releases/latest/download/herd-linux-amd64
chmod +x herd-linux-amd64
./herd-linux-amd64 version

• Work tracking with bw: Run bw prime before starting work.
• Persistent memory with icm: Recall context with icm recall "query" and store updates with icm store.