feat: server-hosted agents via buzz-spawner, with identity relocation (1/4)

[siddhartpai]

Part 1 of a 4-PR stack splitting the server-agent work (supersedes the single mega-branch in #3113):

1. this PR — server-hosted agents, end to end
2. feat: first-party server-agent prompt/model editing (2/4) #3186 — first-party prompt/model editing
3. feat: per-owner credentials for server agents (3/4) #3187 — per-owner Claude credentials
4. docs: self-hosted backend guide and deploy notes (4/4) #3188 — self-hosted guide + deploy notes

Each later PR's diff currently includes its predecessors (fork branches can't be PR bases upstream); review this one first — the later drafts shrink to their own commits as predecessors merge.

---

This is a full vertical slice, not a backend-only PR

Worth setting expectations up front, because the title undersells it: roughly a third of this diff is React.

Area	Files	Lines
crates/* — spawner daemon, SDK, relay, kinds	20	+5,749
desktop/src — React UI and stores	42	+3,622
desktop/src-tauri — Tauri bridge	33	—
Docker / compose / lockfile	7	+404

The UI is not separable polish. The desktop app is the only thing that can sign a NIP-OA attestation, so without it the spawner mints an agent key and then waits forever for an approval nothing can give. The consent flow is what makes the daemon usable at all, and it is the most security-sensitive code here.

What it does

An owner publishes a kind:30178 spec naming a spawner. The spawner mints an agent keypair, asks the owner to attest it over an encrypted kind:24201 handshake, and on approval runs the agent in its own Docker container. Existing local agents can instead be relocated — the same identity moves to the server, keeping its channels, profile, and memory.

owner   ──kind:30178 spec───────────────────────────►  spawner
spawner ──kind:24201 request (agent pubkey + nonce)─►  owner
owner   ──kind:24201 response (NIP-OA auth tag)─────►  spawner
spawner ──kind:30179 status: running────────────────►  owner
                       └──► Docker: one buzz-acp container per agent

Review map

Read line-by-line — signing, key handling, and consent:

• desktop/src/features/agents/trustedSpawners.ts (+115) — which spawners may skip the prompt. Signing admits an agent to the relay under the user's membership.
• desktop/src/features/agents/spawnerAttestationStore.ts (+330) — auto-approval, dedup, and the relocation hand-off ordering.
• desktop/src/features/agents/ui/SpawnerAttestationDialog.tsx (+217) — what the user actually sees before approving.
• desktop/src-tauri/src/commands/spawner.rs (+418) — decrypts the frame, signs the tag, and releases a relocated agent's secret key.
• crates/buzz-spawner/src/attestation.rs (+396) — the spawner-side verification. Pure function; every rejection path is tested.

Read carefully — correctness of the control loop:

• crates/buzz-spawner/src/reconcile.rs (+727) — desired vs actual state. Pure function.
• crates/buzz-spawner/src/env.rs (+376) — what reaches an agent container, and the reserved-key filter that stops operator config overriding an agent's identity.
• crates/buzz-spawner/src/store.rs (+324) — on-disk agent secret keys.
• crates/buzz-relay/* (+244) — NIP-OA delegated persona reads.

Skim — behaviour is covered by tests: everything in *.test.mjs and tests/ (+779), plus owner_sim.

Skip — boilerplate: Dockerfile.*, deploy/compose/*, Cargo.lock, new-crate scaffolding.

Design notes a reviewer may want

• Agent keys are minted on the server and never transmitted. A NIP-OA tag is signed with the owner's key over the agent's pubkey, so the spawner cannot self-attest — hence the two-round handshake.
• Agent containers are kept off the relay's internal network. An agent runs arbitrary shell tools; joining that network would put Postgres, Redis, and MinIO one nc away.
• System prompts travel over the encrypted handshake, never in the world-readable spec.
• Deletion is gated on subscription hydration. Before EOSE an absent spec means "unknown", not "deleted" — reading it as deleted would destroy every agent's container, volume, and key on each restart.

Review fixes already applied

A review pass on this branch found and fixed, in the commits after bb1046a9:

• Trusted spawners were never cleared on community switch — a spawner approved under one identity auto-signed under the next.
• Container and volume names were not spawner-scoped, so two spawners on one host could force-remove each other's live agents in a loop.
• Ephemeral attestation frames arriving during a persona query were dropped, stalling the handshake until timeout.
• The relocation hand-off is now atomic: the local agent is marked relocated and stopped before its key is released, rather than in follow-up IPC calls that could be interrupted.
• Docs that described guarantees the code did not implement (a relay author-gate on kind:30179, NIP-09 teardown, a backend trust check) now describe what actually happens.
• The state file holding agent secret keys is opened 0600 rather than chmod-ed after creation.

Known gap, closed by #3187: a spawner currently accepts specs from any community member, so an operator's host-global API key is reachable by anyone who can publish. Don't deploy this to a shared community until the credentials PR lands.

🤖 Generated with Claude Code