From 219c04a34122a0de7101526a7753c63446dec375 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Tue, 28 Jul 2026 22:38:51 -0700 Subject: [PATCH] docs(integrations): unified Buzz integration overview page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One page consolidating all three Hermes×Buzz integration paths — Desktop managed runtime, buzz-acp relay bridge, and the native gateway platform — with a comparison table, per-path pointers into the detailed docs, identity guidance, and contributor credits. Registered in sidebars.ts under Integrations; Buzz added to the messaging platform list and a new Collaboration Workspaces section on the integrations index. en + zh-Hans. --- website/docs/integrations/buzz.md | 57 +++++++++++++++++++ website/docs/integrations/index.md | 6 +- .../current/integrations/buzz.md | 57 +++++++++++++++++++ website/sidebars.ts | 1 + 4 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 website/docs/integrations/buzz.md create mode 100644 website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md diff --git a/website/docs/integrations/buzz.md b/website/docs/integrations/buzz.md new file mode 100644 index 0000000000000..c0514bf99e472 --- /dev/null +++ b/website/docs/integrations/buzz.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 4 +title: "Buzz Integration" +description: "All three ways to connect Hermes Agent to Buzz — Block's Nostr-based human+agent workspace" +--- + +# Buzz Integration + +[Buzz](https://github.com/block/buzz) is Block's open-source, self-hostable workspace where humans and AI agents share the same channels. It is built on Nostr: every message is a signed event on a relay you own, and every participant — human or agent — is a keypair. + +Hermes integrates with Buzz three ways. Pick by where Hermes runs and what you want it to do: + +| | ① Desktop runtime | ② Relay bridge (ACP) | ③ Native gateway platform | +|---|---|---|---| +| **What it is** | Buzz Desktop spawns Hermes locally as a managed harness | Buzz's `buzz-acp` bridges a channel to `hermes acp` over stdio | Hermes' gateway joins Buzz as a first-class messaging platform | +| **Hermes runs** | On your desktop, launched by Buzz | On a server, launched by `buzz-acp` | In your own gateway, alongside Telegram/Discord/etc. | +| **Best for** | Trying Hermes inside Buzz Desktop with zero config | A hosted agent identity when Buzz owns the transport | Full Hermes: memory, skills, approvals, cron, sessions | +| **Inbound** | ACP stdio | ACP stdio (via relay WebSocket) | NIP-42-authenticated Nostr WebSocket (poll fallback) | +| **Setup** | Automatic discovery | `buzz-acp` env vars | `hermes gateway setup` → Buzz | + +## ① Buzz Desktop managed runtime + +Buzz Desktop ships Hermes as a preset runtime. With Hermes installed the normal way, open **Settings → Runtimes** and Hermes appears automatically — discovery resolves the `hermes-acp` launcher on your login-shell PATH, which the installer writes to `~/.local/bin` (and `hermes update` self-heals on older installs). + +Full setup, troubleshooting, and the security posture (Buzz auto-approves tool permissions — keep agents owner-only): **[ACP Host Integration → Buzz Desktop](/user-guide/features/acp#buzz-desktop)** + +## ② Relay bridge (buzz-acp + ACP) + +For a hosted Hermes identity that joins Buzz *channels* while Buzz's own harness owns the transport: + +```text +Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent +``` + +The spawned Hermes uses the same config, credentials, memory, and skills as `hermes` on that host. Key minting, channel discovery, owner-only telemetry (`BUZZ_ACP_RELAY_OBSERVER`), and headless-permission guidance: **[ACP Host Integration → Buzz channels (relay bridge)](/user-guide/features/acp#buzz-channels-relay-bridge)** + +## ③ Native gateway platform (recommended for full Hermes) + +The bundled `buzz` platform plugin makes Buzz a normal Hermes messaging platform — channels, DMs, mention gating, threaded replies, reactions, images, and cron delivery (`deliver=buzz`), with Hermes' own approvals, memory, and session management intact. Inbound arrives over a persistent NIP-42-authenticated Nostr WebSocket (dependency-free BIP-340 signing) with automatic fallback to CLI polling; outbound goes through the `buzz` CLI. + +```bash +hermes gateway setup # pick Buzz +``` + +Full configuration reference (env vars, config.yaml, transport modes, access control): **[Messaging → Buzz](/user-guide/messaging/buzz)** + +## Which one should I use? + +- **Just exploring, Buzz Desktop user** → ① works out of the box. +- **Running a community relay and want an agent identity managed by Buzz** → ②. +- **You already run Hermes as your agent and want Buzz as another channel** → ③. This is the deepest integration and the one that keeps every Hermes feature. + +①/② and ③ use different identities and transports; run ③ with its own dedicated Nostr keypair. The adapter takes a scoped lock on the relay+pubkey pair, so two Hermes profiles cannot accidentally drive one Buzz identity. + +## Credits + +The Buzz integration was built with the community: @SHL0MS (PATH launcher + Desktop security audit), @NYTEMODEONLY (relay-bridge docs), @rob-coco (platform adapter), @ScaleLeanChris (Nostr WebSocket transport + NIP-42/BIP-340 signing), and @jethac (multi-agent verification). diff --git a/website/docs/integrations/index.md b/website/docs/integrations/index.md index 7f4e1f17679ec..597571eec7e99 100644 --- a/website/docs/integrations/index.md +++ b/website/docs/integrations/index.md @@ -91,10 +91,14 @@ Speech-to-text supports six providers: local faster-whisper (free, runs on-devic Hermes runs as a gateway bot on 27+ messaging platforms, all configured through the same `gateway` subsystem: -- **[Telegram](/user-guide/messaging/telegram)**, **[Discord](/user-guide/messaging/discord)**, **[Slack](/user-guide/messaging/slack)**, **[WhatsApp](/user-guide/messaging/whatsapp)**, **[Signal](/user-guide/messaging/signal)**, **[Matrix](/user-guide/messaging/matrix)**, **[Mattermost](/user-guide/messaging/mattermost)**, **[Email](/user-guide/messaging/email)**, **[SMS](/user-guide/messaging/sms)**, **[DingTalk](/user-guide/messaging/dingtalk)**, **[Feishu/Lark](/user-guide/messaging/feishu)**, **[WeCom](/user-guide/messaging/wecom)**, **[WeCom Callback](/user-guide/messaging/wecom-callback)**, **[Weixin](/user-guide/messaging/weixin)**, **[BlueBubbles](/user-guide/messaging/bluebubbles)**, **[QQ Bot](/user-guide/messaging/qqbot)**, **[Yuanbao](/user-guide/messaging/yuanbao)**, **[Home Assistant](/user-guide/messaging/homeassistant)**, **[Microsoft Teams](/user-guide/messaging/teams)**, **[Microsoft Teams Meetings](/user-guide/messaging/teams-meetings)**, **[Microsoft Graph Webhook](/user-guide/messaging/msgraph-webhook)**, **[Google Chat](/user-guide/messaging/google_chat)**, **[LINE](/user-guide/messaging/line)**, **[ntfy](/user-guide/messaging/ntfy)**, **[SimpleX](/user-guide/messaging/simplex)**, **[Open WebUI](/user-guide/messaging/open-webui)**, **[Webhooks](/user-guide/messaging/webhooks)** +- **[Telegram](/user-guide/messaging/telegram)**, **[Discord](/user-guide/messaging/discord)**, **[Slack](/user-guide/messaging/slack)**, **[WhatsApp](/user-guide/messaging/whatsapp)**, **[Signal](/user-guide/messaging/signal)**, **[Matrix](/user-guide/messaging/matrix)**, **[Mattermost](/user-guide/messaging/mattermost)**, **[Email](/user-guide/messaging/email)**, **[SMS](/user-guide/messaging/sms)**, **[DingTalk](/user-guide/messaging/dingtalk)**, **[Feishu/Lark](/user-guide/messaging/feishu)**, **[WeCom](/user-guide/messaging/wecom)**, **[WeCom Callback](/user-guide/messaging/wecom-callback)**, **[Weixin](/user-guide/messaging/weixin)**, **[BlueBubbles](/user-guide/messaging/bluebubbles)**, **[Buzz](/user-guide/messaging/buzz)**, **[QQ Bot](/user-guide/messaging/qqbot)**, **[Yuanbao](/user-guide/messaging/yuanbao)**, **[Home Assistant](/user-guide/messaging/homeassistant)**, **[Microsoft Teams](/user-guide/messaging/teams)**, **[Microsoft Teams Meetings](/user-guide/messaging/teams-meetings)**, **[Microsoft Graph Webhook](/user-guide/messaging/msgraph-webhook)**, **[Google Chat](/user-guide/messaging/google_chat)**, **[LINE](/user-guide/messaging/line)**, **[ntfy](/user-guide/messaging/ntfy)**, **[SimpleX](/user-guide/messaging/simplex)**, **[Open WebUI](/user-guide/messaging/open-webui)**, **[Webhooks](/user-guide/messaging/webhooks)** See the [Messaging Gateway overview](/user-guide/messaging) for the platform comparison table and setup guide. +## Collaboration Workspaces + +- **[Buzz](/integrations/buzz)** — Block's Nostr-based human+agent workspace. Three integration paths: Buzz Desktop spawns Hermes as a managed ACP runtime, the `buzz-acp` relay bridge hosts a Hermes identity server-side, or the native gateway platform joins Buzz channels with full Hermes memory/skills/approvals/cron. The overview page compares all three. + ## Home Automation - **[Home Assistant](/user-guide/messaging/homeassistant)** — Control smart home devices via four dedicated tools (`ha_list_entities`, `ha_get_state`, `ha_list_services`, `ha_call_service`). The Home Assistant toolset activates automatically when `HASS_TOKEN` is configured. diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md new file mode 100644 index 0000000000000..85ca200f9eca8 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/buzz.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 4 +title: "Buzz 集成" +description: "将 Hermes Agent 连接到 Buzz（Block 基于 Nostr 的人机协作工作区）的全部三种方式" +--- + +# Buzz 集成 + +[Buzz](https://github.com/block/buzz) 是 Block 开源、可自托管的工作区，人类和 AI agent 共享同一批频道。它构建在 Nostr 之上：每条消息都是你自己中继上的签名事件，每个参与者——无论人类还是 agent——都是一个密钥对。 + +Hermes 有三种方式与 Buzz 集成。根据 Hermes 运行的位置和你的需求选择： + +| | ① Desktop 运行时 | ② 中继桥接（ACP） | ③ 原生网关平台 | +|---|---|---|---| +| **是什么** | Buzz Desktop 在本地将 Hermes 作为托管 harness 启动 | Buzz 的 `buzz-acp` 通过 stdio 将频道桥接到 `hermes acp` | Hermes 网关将 Buzz 作为一等消息平台加入 | +| **Hermes 运行在** | 你的桌面，由 Buzz 启动 | 服务器，由 `buzz-acp` 启动 | 你自己的网关，与 Telegram/Discord 等并列 | +| **适合** | 零配置在 Buzz Desktop 中试用 Hermes | 由 Buzz 掌管传输的托管 agent 身份 | 完整 Hermes：记忆、技能、审批、cron、会话 | +| **入站** | ACP stdio | ACP stdio（经中继 WebSocket） | NIP-42 认证的 Nostr WebSocket（轮询兜底） | +| **设置** | 自动发现 | `buzz-acp` 环境变量 | `hermes gateway setup` → Buzz | + +## ① Buzz Desktop 托管运行时 + +Buzz Desktop 将 Hermes 作为预设运行时提供。按常规方式安装 Hermes 后，打开 **Settings → Runtimes**，Hermes 会自动出现——发现机制在登录 shell 的 PATH 上解析 `hermes-acp` 启动器，安装器会将其写入 `~/.local/bin`（较旧安装由 `hermes update` 自动补齐）。 + +完整设置、故障排查和安全注意事项（Buzz 会自动批准工具权限——请保持 agent 为 owner-only）：**[ACP 宿主集成 → Buzz Desktop](/user-guide/features/acp#buzz-desktop)** + +## ② 中继桥接（buzz-acp + ACP） + +适合托管的 Hermes 身份加入 Buzz *频道*，由 Buzz 自己的 harness 掌管传输： + +```text +Buzz relay <-- WebSocket --> buzz-acp <-- ACP over stdio --> Hermes Agent +``` + +被启动的 Hermes 使用该主机上相同的配置、凭据、记忆和技能。密钥铸造、频道发现、所有者遥测（`BUZZ_ACP_RELAY_OBSERVER`）和无头权限指南：**[ACP 宿主集成 → Buzz 频道（中继桥接）](/user-guide/features/acp)** + +## ③ 原生网关平台（完整 Hermes 推荐） + +内置的 `buzz` 平台插件让 Buzz 成为普通的 Hermes 消息平台——频道、私信、提及门控、话题回复、表情回应、图片和 cron 投递（`deliver=buzz`），同时保留 Hermes 自己的审批、记忆和会话管理。入站通过持久的 NIP-42 认证 Nostr WebSocket（无依赖 BIP-340 签名）到达，自动兜底到 CLI 轮询；出站通过 `buzz` CLI。 + +```bash +hermes gateway setup # 选择 Buzz +``` + +完整配置参考（环境变量、config.yaml、传输模式、访问控制）：**[消息平台 → Buzz](/user-guide/messaging/buzz)** + +## 该选哪一个？ + +- **Buzz Desktop 用户，只是探索** → ① 开箱即用。 +- **运营社区中继，想要由 Buzz 托管的 agent 身份** → ②。 +- **已把 Hermes 作为你的 agent，想把 Buzz 作为又一个频道** → ③。这是最深度的集成，保留 Hermes 的全部能力。 + +①/② 与 ③ 使用不同的身份和传输；请为 ③ 铸造专用的 Nostr 密钥对。适配器会对 relay+pubkey 组合加作用域锁，因此两个 Hermes profile 不会意外驱动同一个 Buzz 身份。 + +## 致谢 + +Buzz 集成由社区共同构建：@SHL0MS（PATH 启动器 + Desktop 安全审计）、@NYTEMODEONLY（中继桥接文档）、@rob-coco（平台适配器）、@ScaleLeanChris（Nostr WebSocket 传输 + NIP-42/BIP-340 签名）、@jethac（多 agent 验证）。 diff --git a/website/sidebars.ts b/website/sidebars.ts index 1f4832611bb77..360c95ccbc082 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -678,6 +678,7 @@ const sidebars: SidebarsConfig = { 'integrations/index', 'integrations/nous-portal', 'integrations/providers', + 'integrations/buzz', 'user-guide/features/mcp', 'user-guide/features/acp', 'user-guide/features/provider-routing',