Module cluster

Expand description

Raft between orch nodes. Only coordination state goes through the log, the design is in docs/specs/2026-10-26-multi-machine-cluster-design.md.

Modules§

config: The cluster: section of the global config
discovery: Finds the other orch nodes on the tailnet from tailscale status --json
local: The localhost endpoint the CLI sends replicated writes to, so they go through the daemon’s log
network: Raft RPCs and forwarded writes between nodes, JSON over HTTP like ../agents-coordination. Every request carries the cluster secret, so reaching the port is not enough to join
progress: orch progress: what an agent finished, what is left, and where the work is. The record goes through the log, the session and the worktree stay on the node that runs the task

Member: One member as the leader sees it, for orch nodes
Node: A running node. The store holds one and sends every replicated write through it
NodeConfig: How one node of a cluster starts: its id, the address it listens on, the shared secret, the voters to initialize with, and whether it may lead (a witness may not)
RaftStore: The log and vote live in raft.db, the state machine is orch’s own database. Apply writes each entry and raft:applied in one transaction on orch.db, so a crash never applies an entry twice, and a log that runs ahead of the state is normal for Raft
Request: One replicated write. The proposer stamps now, so every node applies the same value
TypeConfig

Command
Reply: A failed command is Err on every node, so one bad command cannot stop the state machine

enabled: A cluster: section turns the cluster on. Without one, orch writes straight to SQLite as it always has
members
now_stamp: The proposer’s clock, in the format the store writes timestamps in
start: Start this machine’s node from the cluster: section and the tailnet. A learner keeps asking the cluster to add it until a member proves the secret and takes it
start_node: Start one node of a cluster and serve its RPCs on cfg.addr. Every voter initializes with the same membership, which openraft accepts, so no voter is special
start_single: Start a one-node cluster over store, with its log in raft_db, and route the store’s replicated writes through it