A grid is several blumi serve gateways on a LAN that share one secret. Same secret = same grid. Nodes auto-discover each other and the orchestrator (the node your phone connects to) hands tasks off to peers, which execute them on their own runtime/workspace and stream results back. This lets you run a fleet of machines as one.

Status: grid config + peer discovery (/api/grid/peers) are live. Task hand-off (dispatch) and the distributed loop are rolling out incrementally — this page documents the full setup; dispatch behavior lands as those pieces merge.

• One shared grid.secret on every node. Holding the secret = membership.
• The secret is never advertised over mDNS — only a non-reversible grid_id digest is, so peers recognize same-grid nodes without exposing the secret. (Same secret ⇒ same grid_id automatically.)
• Keep the secret in settings.json (mode 0600) or inject it via BLUMI_GRID__SECRET.

On each machine (mix of macOS + Linux is fine):

1. Install blumi → Installation and configure a provider → Configuration.
2. Enable the grid with the same secret. In ~/.blumi/settings.json:

   "grid": {
    "enabled": true,
    "secret": "one-shared-secret-for-the-whole-grid",
    "node_name": "mac-mini"
   }

   ...or via env (e.g. in the service environment): BLUMI_GRID__SECRET=one-shared-secret.
3. Run the gateway as a service → Gateway:

   blumi serve install --host <this-machine-LAN-ip>

That's it — nodes with the same secret find each other on the LAN.

From any node (authenticated), list the peers it can see:

curl -H "Authorization: Bearer <token>" http://<node-ip>:7777/api/grid/peers

{
 "self": { "node_name": "mac-mini", "grid_id": "a1b2c3d4e5f6", "version": "0.1.0" },
 "peers": [
 { "id": "linux-box._blumi._tcp.local.", "name": "linux-box",
 "host": "10.0.0.7", "port": 7777, "online": true, "grid_id": "a1b2c3d4e5f6" }
 ]
}

Get <token> from POST /api/login (the gateway password), or just view the peer list in the blugo app / TUI.

The orchestrator owns the task board. When you run the loop in grid mode, it picks an available peer for each task, dispatches the work, and tags the task with the executing peer — so the TUI board and the blugo task list show which tasks are remote and on which node.

Tasks must be self-contained: a peer runs in its own workspace, so name the repo/branch/paths in the task rather than assuming "the current directory."

• Grid traffic between nodes is authenticated by the shared secret (separate from the human password used by browsers/the app).
• Rotating the secret = restart every node with the new value (identity + discovery are set at startup).
• Keep nodes on a trusted LAN; the grid is not designed to be exposed to the public internet.