buzz/docs/buzz-shared-compute-dev.md

Buzz shared compute: local GUI verification

This runbook verifies the actual desktop path used by the built-in Fizz agent:

Buzz Desktop → buzz-acp → buzz-agent → MeshLLM SDK → local/remote compute

It does not use a substitute agent harness.

Before starting

Run from the block/buzz repository root on the mesh-enabled branch.

For a completely fresh, deterministic local state, use:

. ./bin/activate-hermit
just mesh-dev-fresh

This removes development app data, the development keyring entry, ~/.buzz-dev, and local Docker volumes; it preserves the installed Buzz app's data, production keyring, and ~/.buzz. The first dev page load also clears only that dev server origin's WebKit storage, so saved fields from an earlier run cannot leak into the fresh state. It then seeds local channels and starts the mesh-enabled desktop with the repository's public Tyler test identity. That identity is a fixture and must never be pointed at staging or production.

If using mesh-dev-fresh, the clean window opens at Welcome to Buzz. Join the seeded local community before continuing:

1. Click Join a community.
2. Use any local name, such as Local Buzz.
3. Set Community URL to ws://localhost:3000 and join.
4. Complete the short profile setup if it appears.

The recipe already supplied the repository's public test identity and seeded the local channels. Do not import or generate another key. Continue at Share this machine below.

Free the development ports if a previous run was interrupted:

lsof -nP -iTCP:3000 -iTCP:8080 -iTCP:9102 -iTCP:9337 -iTCP:3131

Stop only stale Buzz/MeshLLM processes shown by that command. Do not leave a standalone mesh-llm process using 9337 or 3131; the desktop owns those ports during this test.

1. Launch the mesh-enabled desktop

. ./bin/activate-hermit
just mesh=1 dev

Keep that terminal open. The first run may build/install the native runtime and take several minutes. Wait for the Buzz window to open and for the terminal to stop printing build progress.

Using plain just dev is not sufficient: the Compute UI and embedded MeshLLM runtime are behind the mesh-llm feature.

2. Share this machine

1. Open Settings.
2. Select Compute.
3. Under Share compute, choose a suggested model.
   • On a 16 GB Apple Silicon machine, use a suggested Qwen3.5 4B quantized model when available.
   • unsloth/Qwen3.5-4B-GGUF:Q4_K_M is the model used by the hardware proof.
   • Do not use a sub-1B model for the channel-reply proof. It can prove that inference is reachable while still failing the agent's long prompt and required message-send tool call.
4. Turn on Share this machine.
5. Wait until the card says it is sharing/running. Do not start Fizz while the card says downloading, preparing, or starting.

Buzz may download the model on first use. The model picker ranks models for the current hardware; avoid entering a model the card marks too large.

3. Make shared compute the agent default

1. Open Agents from the left sidebar.
2. In Agent defaults, set Default LLM provider to Buzz shared compute.
3. Set Default model to Default (auto).
4. Click Save defaults and wait for Saved.

Fizz has no pinned runtime/provider/model, so it inherits these defaults and resolves to the bundled buzz-agent. No API key is required.

4. Start the real Fizz path

1. Find the Fizz card on the Agents screen.

2. If Fizz is stopped, click the small play badge over its avatar. If it is running, the badge is a green status dot instead of a stop control.

3. Wait for its runtime indicator to become active.

4. Add Fizz to a channel if it is not already a channel member.

5. In that channel, send:

   @Fizz Reply exactly: FIZZ_MESH_OK
   

6. Confirm that Fizz replies FIZZ_MESH_OK in the channel.

That channel response is the end-to-end proof. A green Compute card alone proves only model serving; it does not prove the Fizz harness and provider inheritance.

To stop a running agent, click the body/name of its card to open its profile, then click Stop near the top. The green avatar badge is status-only while the agent is running. Once stopped, the profile action becomes Respawn and the avatar badge becomes a play button.

To create a separate test agent, choose New agent → New agent, use buzz-agent as the runtime, Buzz shared compute as the LLM provider, Default (auto) as the model, and This computer under Run on. Shared compute is an LLM provider; do not select a remote compute backend as the run location merely because its name mentions mesh.

5. Optional diagnostics

While Buzz is running:

# The desktop should own both ports.
lsof -nP -iTCP:9337 -iTCP:3131

# The embedded OpenAI-compatible ingress should advertise the model.
curl -sS http://127.0.0.1:9337/v1/models | jq '.data[].id'

# Fizz should resolve through the real managed-agent subprocesses.
ps -eo pid,ppid,command | grep -E '[b]uzz-(desktop|acp|agent)'

If Fizz fails, open its runtime details from the Agents screen first. Common causes are:

• launched with just dev instead of just mesh=1 dev;
• a stale process owns 9337/3131;
• the model is still downloading or preparing;
• Fizz is not a member of the channel;
• defaults were changed but not saved;
• no current Buzz membership snapshot is available (admission fails closed).

Security boundary

Buzz publishes member-signed discovery notes through an ordinary relay-supported NIP-51 event. The note includes a MeshLLM-key signature binding the member to the advertised MeshLLM node identity, plus a second signature over the exact endpoint tokens in the note. Current Buzz membership controls which node identities are admitted. A serving target is selectable only when its endpoint signature is valid, its invite token decodes as a bounded Iroh endpoint, and every advertised relay URL matches this machine's locally configured Iroh relay policy.

BUZZ_MESH_IROH_RELAYS defaults to Iroh's production relay set. Set it to 0 for direct QUIC only, or to a comma-separated HTTPS allowlist for custom relays. Plain HTTP is accepted only for loopback development relays. Remote status notes cannot expand this local allowlist.

MeshLLM—not the Buzz relay—carries inference over direct QUIC or its encrypted iroh relays and enforces the owner allowlist. The dependency is pinned to the post-v0.72.2 admission fix that prevents a non-member with a leaked invite token from using passive inference streams. MeshLLM v0.73.1 still performs its owner check during gossip after transport connection; authenticating before any gossip is an upstream protocol change and is not claimed by the Buzz-side checks above.