block / block/buzz

Allow channel templates to attach existing relay agents by identity

Open
#5,355 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

## Problem

Channel templates currently describe agent rosters through local persona and team IDs. Applying a template resolves those definitions on the Desktop installation applying it and may create or reuse locally managed agent instances.

That behavior is a poor fit for a distributed Buzz workspace where agent identities already exist on the relay but their runtimes are hosted elsewhere, for example:

- headless `buzz-acp` agents supervised by systemd on a VPS;
- agents running on another desktop;
- provider-managed or Kubernetes agents;
- a stable team split across several devices.

In that topology, the existing agents can be visible in the relay directory and already have stable pubkeys, channel memberships, keys, and launchers. Applying a persona/team template from another Desktop can nevertheless create duplicate identities or start compute on the wrong machine instead of attaching the existing agents.

## Proposed capability

Allow a channel template roster entry to explicitly choose between:

1. **Deploy from persona/team**: retain today's behavior and create or reuse a locally/provider-managed instance.
2. **Attach existing agent identity**: reference an existing relay-visible agent by pubkey and only add that identity to the new channel.

For an existing-identity entry, applying the template should:

- add the referenced pubkey using the configured channel role;
- leave its private key, runtime, launcher, and lifecycle untouched;
- never silently mint a replacement when the identity is missing or unavailable;
- report unresolved entries and partial membership failures clearly;
- work without the applying Desktop possessing the agent's private key;
- avoid treating relay presence as permission to control the remote process.

A template could therefore reproduce a fixed distributed roster while each agent continues running wherever its key and harness are already installed.

## Example

A reusable engineering roster contains these stable identities:

- planner/research agents running on a Windows workstation;
- implementation/review agents running lazily on a VPS.

Creating a feature channel from a template should attach those same pubkeys. It should not create a second Codex, Claude, or Cursor instance on the Windows machine that applied the template.

## UX considerations

The template editor could present separate sections or modes:

- **Agent definitions to deploy**
- **Existing agents to attach**

Existing entries should be selected from relay directory identities with their pubkey prefix and execution/management status shown, so duplicate display names are unambiguous.

## Authorization and security

Applying the template must use the existing channel membership authorization path. Referencing a pubkey grants no ability to read its private key, change its runtime, or manage its remote launcher.

## Related work

- #2728 proposes pubkey-backed groups and bulk channel membership. A future group reference may be another way to express an attach-only roster, but templates still need semantics that distinguish attachment from deployment.
- #2987 and #3204 cover discoverability and mentionability of externally managed agents. This request assumes those agents can be represented in the UI and focuses on reusable channel provisioning without identity duplication.

## Contribution

I am willing to help implement this if the maintainers agree with the direction and can provide guidance on the preferred template schema and UI.

Contributor guide

Open the contributing guide

Research direction

No files or tests are named. Start by tracing channel-template roster resolution and the existing channel membership authorization path; then identify where deployment entries can be distinguished from attach-only pubkey entries. Done means templates can attach existing relay identities without local deployment, private-key access, or silent replacement, while reporting unresolved entries and partial membership failures.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
distributed-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.