Repository navigation
RFC: App-integration agents — install a Buzz-managed agent that carries an app's own tools + scoped credentials (headless, owner-approved) #3227
Description
Summary
A stable, scriptable way for a third-party app to install a Buzz-managed
agent that carries the app's own tools + a scoped credential — so the agent
does real domain work (not just chat) while Buzz hosts + supervises it. Today a
managed agent (Fizz/Bumble/Honey) is a general assistant with no app tooling, and
the only way to give one app-specific tools + secrets headlessly is blocked.
Concrete use case (what drove this)
Figura is a design tool. We wanted a Buzz-native Figura agent: mention it in a
channel → it builds an on-brand UI mock ("fig") and replies with a link, answers
"what figs do we have?" via our CLI, iterates on a fig in-thread. That needs the
agent's harness to carry:
- the
figuraCLI +/figskill (its tools), - a scoped team token (which team's brand + where figs land),
- a persona/system prompt.
A builtin:fizz-style managed agent can't do this — it has no Figura tooling or
credential. So we ended up shipping a self-hosted daemon (own Nostr key,
channels add-member, launchd) as a workaround. That works, but:
- It doesn't scale to co-hosts. If two teammates each run the daemon in the
same channels, both fire on@figura→ duplicate replies, duplicate figs, each
burning its own model subscription. There's no cross-daemon dedup. A single
Buzz-managed agent per community would solve this by construction.
Why the managed path is blocked today
- Managed agents can't carry app tools + secrets headlessly. Desktop's
Create-agent → Advanced setsruntime.mcpCommand+env_vars, but the CLI
agents draft-createpath is a deliberately no-secret owner-review contract
(parseAgentManagementRequestdrops any secret-shaped/unknown key). So an app
installer can't hand over a token/tool via the draft. (CLI: expose --mcp-command and --env onbuzz agents draft-create/draft-update(GUI Advanced parity) #3115 tried the CLI flag
and ran into exactly this.) - Headless provisioning needs a Desktop-minted attestation.
draft-create
requiresBUZZ_AUTH_TAG(NIP-OA owner attestation), which only Desktop mints —
there's no CLI to produce it. So the flow can't run from an app'ssetup. - The deep-link prefill (feat(deep-link): add buzz://install-agent prefill arm #2911) still routes to the owner's Desktop form and
isn't in released builds.
Net: there's no path for "app X installs its working agent into my community" that
carries X's tools + a scoped secret, with owner approval but without hand-walking
the GUI.
Ask
A stable extension point to register/install a managed-agent bundle:
{ personaId, displayName, systemPrompt,
harness, // e.g. claude-code
tools: { mcpCommand | mcpServers },
credentials: [ vaultRef ], // scoped secret, egress-substituted, never in the
// owner-review draft or the sandbox
defaultChannels }
- Owner-approved, not owner-hand-authored. The owner still consents (one
approval), but an app can prefill the whole bundle headlessly. - Secrets handled safely — a vault/secret-ref the harness resolves at egress,
distinct from the no-secret draft contract (so CLI: expose --mcp-command and --env onbuzz agents draft-create/draft-update(GUI Advanced parity) #3115's boundary stays intact). - This is the layer beneath the marketplace (RFC: Cross-community agent marketplace (discovery + install) built on the shared-persona catalog and buzz://install-agent #2958): the marketplace discovers/
installs; this defines what a working, tool-carrying installed agent IS.
Relates to
- RFC: Cross-community agent marketplace (discovery + install) built on the shared-persona catalog and buzz://install-agent #2958 — Cross-community agent marketplace (discovery/install)
- RFC: Stable extension points for downstream integrations and distributions #2754 — Stable extension points for downstream integrations (MCP tools + agent lifecycle is one bullet; this is the concrete agent-bundle case)
- CLI: expose --mcp-command and --env on
buzz agents draft-create/draft-update(GUI Advanced parity) #3115 — CLI--mcp-command/--env(blocked by the no-secret draft contract) - feat(deep-link): add buzz://install-agent prefill arm #2911 —
buzz://install-agentdeep-link prefill
Happy to share the Figura self-hosted-daemon design as a reference for what a
managed equivalent would need to replace.
Activity
asymetryk commentedon Jul 30, 2026
Thanks for opening this RFC. I’m implementing a self-hosted Agent Workforce where Buzz is the human collaboration, approval, and provenance surface, while an external AgentInfra control plane owns credential and token lifecycle.
A separation that looks important in practice is:
vaultRef/secret handle, never the credential itself.The corresponding human loop belongs naturally in Buzz: connection readiness, re-auth requests, permission approvals, failures, and receipts in the Inbox; capability/readiness visibility on the agent before delegation.
This seems closely related to #2282, #2754, #2931, and draft #3275. Would maintainers prefer the Connection / Data Source / Grant contract to be developed inside this RFC, or as a separate focused RFC that this issue can depend on?
I’m going to prove a private metadata-and-policy MVP first without migrating existing provider tokens, and I’d be glad to bring back the schema and implementation lessons before proposing small upstream PRs.
asymetryk commentedon Aug 2, 2026
Update after proving the private metadata-and-policy MVP end to end:
We now have a working pilot where a native Buzz mention routes to an external agent runtime, the runtime discovers only its assigned connection alias, and a separate connection plane authorizes access to one bounded data source. In the pilot, the agent could list its connection, search one Gmail mailbox, and read one result. The same identity was denied create, update, delete, and send; unsigned calls and unassigned aliases also failed closed. The decision audit recorded search/read and zero mailbox mutations.
What held up well in practice:
A minimal Buzz-facing management surface could therefore be three views:
The smallest upstream boundary does not need Buzz to become the vault. It could be:
The attached concept is intentionally operational rather than a decorative dashboard. It shows multiple accounts, data-source readiness, and explicit per-agent verbs without exposing credential values.
Would maintainers prefer this as a focused RFC that #3227 depends on, or should the contract continue to develop directly in this thread? I can share a reduced schema, decision examples, and tests from the private pilot without including provider credentials or deployment-specific internals.