The blumi grid turns several machines on your local network into one fleet that runs blumi coding-agent tasks in parallel. A grid is a set of blumi serve gateways that share one secret; nodes auto-discover each other, and the orchestrator (the node your phone connects to) hands tasks to peers that run them on their own runtime and workspace and stream the results back, each tagged with the machine that produced it. blumi is a terminal-first AI coding assistant, and the grid is how you spread its work across a Mac, a Linux box, and more — all on your LAN (local area network), with nothing sent to the cloud.

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. Run a fleet of machines as one — and when compute is expensive, none of it sits idle.

• A blumi grid is several blumi serve gateways on a LAN sharing one grid.secret — same secret means same grid.
• Membership is the secret: holding grid.secret makes a node part of the grid; the secret is never advertised.
• Discovery is automatic over mDNS (multicast DNS, _blumi._tcp), with optional static peers for networks where multicast is blocked.
• The orchestrator delegates tasks to peers, which run them in their own workspace and stream results back, each tagged by machine (hostname + OS).
• Three ways to delegate: the blugo Grid tab (POST /api/grid/delegate), the grid_dispatch chat tool, and the distributed blumi loop task board.
• Direct dispatch works on any model — the Grid tab does not depend on the model deciding to call a tool.
• GPU-aware: a CPU-only node can offload embeddings to the strongest GPU peer (CUDA > Apple CoreML > CPU) via POST /api/grid/embed.
• LAN-only: node-to-node traffic is authenticated by the shared secret (X-Blumi-Grid header); the grid is not designed for the public internet.

The blumi grid lets several machines on your network act as one blumi fleet. Every node runs a blumi serve gateway configured with the same grid.secret. Nodes with a matching secret recognize each other and discover peers automatically over mDNS. When you delegate a task, the orchestrator — the node your phone is connected to — fans it out to one peer or all peers; each peer executes the task in its own runtime and workspace and streams results back, tagged with the hostname and OS that ran it. The result: a fleet of machines you drive as one, with no machine sitting idle when compute is expensive.

Status: live. Peer discovery (mDNS + optional static peers), per-machine task delegation from the phone (blugo Grid tab), the chat-driven grid_dispatch tool, and the distributed blumi loop all work today. Every result is tagged with the machine that ran it.

Animated network flow of grid task execution: blugo to orchestrator to peers and back
Grid task execution — a task from blugo fans out across the grid and the results return, tagged by machine.

blumi running at once across a MacBook Air, a MacBook Pro, a Linux laptop, and a foldable phone

No — the grid is LAN-only and nothing goes to the cloud. Membership is a shared secret, the secret itself is never advertised over the network, and all node-to-node traffic is authenticated by that secret and meant to stay on a trusted local network.

• 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.)
• Keep the secret in settings.json (mode 0600) or inject it via BLUMI_GRID__SECRET.
• Node-to-node grid traffic is authenticated by the shared secret via the X-Blumi-Grid header (separate from the human password browsers/the app use). Keep nodes on a trusted LAN.

Set the same grid.secret on every machine, run each as a blumi serve service, and restart so they re-read the config — nodes with a matching secret then find each other automatically. On each machine (mixing 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",
    "peers": ["10.0.0.150:7777", "10.0.0.113:7777"]
   }

   ...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>

4. Restart the gateway after editing settings so it re-reads the grid config:
   • macOS: launchctl kickstart -k gui/$(id -u)/com.blumi.serve
   • Linux: systemctl --user restart blumi-serve

Nodes with the same secret find each other on the LAN automatically.

• mDNS (_blumi._tcp) is automatic on a normal LAN — leave peers empty.
• Static peers (peers: ["IP:port", ...]) are for networks where multicast is blocked — or after a fresh ad-hoc code-sign on macOS resets the Local-Network permission (which silences mDNS). Static peers are mDNS-independent: list each other node's IP:port and discovery is instant on gateway start. A node that's both statically listed and mDNS-discovered is de-duplicated by host:port (the friendly mDNS name wins).

From any node (authenticated), list the peers it can see — or just open blugo → Control Center → Grid, which lists live peers:

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 /api/grid/metrics aggregates each peer's live node metrics (tasks + tokens + accelerator) for the same view, with a strongest peer summary.

Each node reports its accelerator in /api/grid/metrics and the grid ranks a strongest peer (CUDA > Apple CoreML > CPU). A CPU-only node can put that to work: set

"embeddings": { "backend": "grid" }

and it offloads embedding to the strongest GPU peer via a secret-authed POST /api/grid/embed (the same X-Blumi-Grid trust as the rest of the grid), with a TTL-cached peer choice and a local/FTS5 fallback when no peer is up. So a lean Linux box can ride a Mac (CoreML) or CUDA peer for vectors without building the heavy embedder locally. See Memory & Knowledge → GPU acceleration.

The TUI, web UI, and blugo are all renderers of one UI-agnostic core: a turn flows Command → session actor → tools → grid, and streams back as Events that re-render every surface. grid_dispatch (and the deterministic /api/grid/delegate) are just tools/endpoints that hand a prompt to the grid client.

blumi TUI architecture and request/response process flow

There are three ways to spread work over the grid: the blugo Grid tab (deterministic, any model), the grid_dispatch chat tool, and the distributed blumi loop task board. Every result is tagged with the machine (hostname + OS) that produced it, and live runs stream into any TUI/blugo via /remote attach.

Open blugo → Control Center → Grid:

• Live peers — every node currently in the grid.
• Run on — pick all peers (broadcast) or one specific peer.
• Type a task, tap Delegate over grid → each machine runs it as one turn and reports back — hostname, output, and latency — in per-machine result cards.

This goes through POST /api/grid/delegate, a direct dispatch: it does not rely on the model deciding to call a tool, so it works even with smaller local models.

blugo Grid delegation tab with per-machine results

In any chat (TUI, web, or blugo) the agent can call grid_dispatch to run a prompt on a peer (round-robin or named) and bring the result back, collating a multi-machine answer in one reply — great for "compare this across my machines" asks. (Needs a model that reliably calls tools; for a guaranteed run regardless of model, use the Grid tab above.)

grid_dispatch fan-out across peers in blugo per-machine grid benchmark leaderboard

The orchestrator owns the task board. In grid mode the loop round-robins board tasks across live peers, claims each with the executing peer as owner, runs it on that peer, and advances it — so the TUI board and the blugo task list show which tasks are remote and on which node. Start it with POST /api/loop/start {"mode":"grid"}.

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."

The same job runs live on each peer — attach a TUI to any gateway with /remote self to watch (each peer needs a self remote pointing at its own LAN IP, e.g. http://10.0.0.7:7777):

blumi TUI executing on the macOS (Apple Silicon) peer blumi TUI executing on the Linux (x86_64) peer

For a full hands-on walkthrough, see Grid Demo .

• The gateway's first outbound call right after a restart can fail instantly (cold HTTP connector / macOS Local-Network warm-up); it succeeds on the next call.
• 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.

No. The blumi grid is LAN-only: nodes talk to each other directly over your local network, traffic is authenticated by the shared grid.secret via the X-Blumi-Grid header, and the grid is not designed to be exposed to the public internet. Each peer runs tasks on its own machine — your code stays on the machines you control.

Automatically over mDNS (multicast DNS, service type _blumi._tcp) when they share the same grid.secret. For networks where multicast is blocked, list each other node's IP:port under peers for instant, mDNS-independent discovery. A node that is both statically listed and mDNS-discovered is de-duplicated by host:port.

The shared secret. Every node with the same grid.secret belongs to the same grid (same secret ⇒ same grid_id). The secret is never advertised — only a non-reversible grid_id digest is — so peers recognize same-grid nodes without exposing the secret.

Yes. The blugo Grid tab uses POST /api/grid/delegate, a direct dispatch that does not depend on the model deciding to call a tool, so it works on any model. The grid_dispatch chat tool is the alternative for models that reliably call tools.

Each node reports its accelerator in /api/grid/metrics and the grid ranks a strongest peer (CUDA > Apple CoreML > CPU). A CPU-only node that sets "embeddings": { "backend": "grid" } offloads embedding to that strongest GPU peer via a secret-authenticated POST /api/grid/embed, with a TTL-cached peer choice and a local/FTS5 fallback when no peer is available.

You must restart every node with the new value, because grid identity and discovery are set at startup. Until a node restarts with the matching secret, it won't recognize the others.