RFC: Machine-level enrollment for headless/self-host — join once, then freely create many agents (Raft-like)

[tianheil3]

Summary

Self-hosters want a Raft-like / Multica-like UX for agents:

1. Enroll a machine once against a community relay (including headless Linux servers).
2. On that machine, freely create / start / stop multiple agents (each with its own identity + runtime, e.g. Grok Build / Codex / Claude).
3. Human clients (Desktop on Windows/Mac, mobile, web) only join the same relay to chat and @ agents — they should not need to host the always-on process.

Today this is only smooth for local Desktop-managed agents. Headless and multi-machine still feel like N independent buzz-acp processes with hand-rolled env/systemd, and cross-machine @ is broken in several ways.

Why (user story)

My community relay runs on a Debian box (no GUI). I use Buzz Desktop on Windows only as a chat client. I want 24×7 agents whose runtime lives on the server (or on other machines), not on my laptop. Ideal: one “join this machine to the community” step, then create as many agents as I want on that machine—same mental model as installing Desktop once and then creating agents under Agents/runtimes.

What already exists (related)

Please treat this as an umbrella / product-shape request; several open issues already touch pieces:

Issue	Relevance
#2859 feat(spawner): first-party server-hosted agents via a buzz-spawner daemon	Closest server-side path: daemon reconciles agent specs → Docker buzz-acp. Strong foundation.
#3204 / #2508 / #2349 / #3277	Remote / other-machine agents missing or wrong in @ picker — multi-machine usability.
#2987 / #3054	External (non-desktop-managed) agents visibility / mention rules.
#2958	Marketplace + buzz://install-agent discovery/install.
#3227	App-integration / headless managed agents (owner-approved).
#3399	Configurable ACP runtime registry (3rd-party runtimes).
#3457	Grok Build spawn args bug (grok TUI vs grok agent … stdio).

This issue does not replace #2859; it asks for an explicit machine enrollment + multi-agent operator UX on top of (or alongside) spawner/ACP, so self-hosters get the “one machine, many agents” loop without owning the desktop process tree.

Proposed product shape (non-normative)

[Human Desktop / mobile]  --WS-->  relay (community)
[Machine agent host]      --WS-->  relay
   machine-enrollment (once)
   └── agent instances N (keys, runtime, systemd/docker)

Concrete capabilities (any subset helps):

1. Machine join: documented one-shot bootstrap (binary or compose) with BUZZ_RELAY_URL + operator auth; records “this host is an agent runtime node for community X”.
2. Agent create on host: CLI or small local API: create --name … --runtime grok|codex|… → mint/register identity, membership, start harness; list/stop/restart.
3. No laptop dependency for uptime: agents keep running when Desktop is closed (overlap with feat(spawner): first-party server-hosted agents via a buzz-spawner daemon #2859).
4. Mention parity: any community member can @ agents that are channel members regardless of which machine hosts the runtime (overlap with Mention picker lists locally-managed agents instead of channel members, so an agent running on another machine can never be @-mentioned #3204 family).
5. Optional: relay/admin UI “copy enroll command for a new machine” (operator convenience only; process still runs on the enrolled host).

Out of scope / non-goals

• Replacing Nostr agent identity with seat licenses.
• Running untrusted agent code inside the relay process (agree with feat(spawner): first-party server-hosted agents via a buzz-spawner daemon #2859: spawner as sidecar).
• Forcing all agents through Docker if the operator prefers bare systemd + buzz-acp.

Ask

• Confirm whether feat(spawner): first-party server-hosted agents via a buzz-spawner daemon #2859 is the intended vehicle for headless multi-agent hosts.
• If yes: please link/accept a short “machine enrollment + create-many-agents” UX checklist on that issue (or a design doc).
• If no / partial: track the machine-level UX here and stack-rank vs spawner.

Happy to refine acceptance tests (enroll server A, create 2 agents with different runtimes, @ from Windows Desktop on same relay, agents reply while Desktop closed).

Context

Self-hosted relay on a headless Linux host; Desktop used only as a client; desire for Grok Build (and other ACP) runtimes as always-on community members.