Hermes In Buzz

Hermes in Buzz

Overview

Set up a dedicated Hermes Agent running on one machine as a native messaging agent in a Buzz community used from another machine. The default topology is:

Buzz Desktop / web client
          |
          v
      Buzz relay
          ^
          | Nostr WebSocket + buzz CLI
          |
Remote Hermes gateway

The client PC does not SSH into the Hermes host. Both independently connect to the same Buzz relay, and Buzz Desktop may be offline while Hermes continues running.

This skill executes the setup, not merely describes it. Continue until the CLI works, relay authorization succeeds, the gateway logs buzz connected, and one inbound plus outbound message has been verified.

Authoritative docs change quickly. At the start of every run, load the hermes-agent skill and inspect:

• https://hermes-agent.nousresearch.com/docs/integrations/buzz
• https://hermes-agent.nousresearch.com/docs/user-guide/messaging/buzz
• https://hermes-agent.nousresearch.com/docs/user-guide/features/acp
• the latest stable block/buzz release and its actual assets

If docs and this skill differ, follow the docs and patch this skill after the successful run.

When to Use

Use when:

• Buzz Desktop is on one computer and Hermes should run continuously on another;
• a user says they created a Buzz agent but the Hermes gateway is silent;
• errors progress through buzz CLI binary not found, relay_membership_required, zero channels, or ignored mentions;
• moving an existing native Buzz/Hermes gateway to Linux, macOS, Windows, or WSL.

Do not use this native-gateway workflow when the user explicitly wants Buzz to own the runtime and show ACP activity. In that case use the official buzz-acp relay-bridge guide. Do not improvise an SSH-stdio bridge unless the user explicitly requests an experimental design.

Hard Security Rules

1. Use a dedicated agent identity. Never reuse the human Buzz nsec as BUZZ_PRIVATE_KEY.
2. Never ask for an nsec, API token, or owner key in chat or via clarify.
3. Secret input must be local and hidden (getpass, Read-Host -AsSecureString, or equivalent), never argv.
4. Never print, log, persist temporarily, or return owner private-key material.
5. Store the agent key and BUZZ_AUTH_TAG only in the active profile's Hermes secret environment file. Resolve HERMES_HOME; do not assume ~/.hermes when a profile is active.
6. Use hermes config set for non-secret settings. Never hand-edit config.yaml.
7. Default to allow_all_users: false, an explicit owner allowlist, and require_mention: true. Do not broaden access merely to diagnose delivery.
8. Ask approval before installing Rust, Git, build tools, downloading Buzz, or changing persistence/service configuration.
9. An ACP-hosted Hermes can execute terminal tools without a visible approval because Buzz may auto-answer ACP permissions. Keep ACP agents owner-only. Native gateway approvals retain Hermes gateway semantics.

Phase 1: Discover the Host and Choose the Architecture

1. Detect OS, architecture, shell, active Hermes home/profile, service manager, and tool availability. Check at least hermes, git, cargo, rustc, and buzz/buzz.exe. On Windows distinguish native Windows from WSL.
2. Run hermes status, hermes gateway status, and inspect redacted BUZZ_* presence. Never print secret values.
3. Confirm the intended architecture:
   • Native gateway (default): full Hermes memory, skills, normal sessions, DMs, cron delivery, images, reactions, threaded replies, and multiple messaging platforms in one gateway.
   • Relay bridge (buzz-acp): Buzz owns transport; Hermes runs in ACP mode on the server; reduced ACP-oriented surface and stronger owner-only warning.
   • Buzz Desktop runtime: Hermes runs on the same computer as Buzz Desktop, not the remote-host goal.
4. Collect only non-secret facts in chat: relay URL, desired agent display name, owner public npub, intended channels/home channel, and whether other community members may invoke it.

Completion criterion: topology and access policy are explicit, no secret has appeared in conversation, and native gateway is selected unless the user chose otherwise.

Phase 2: Obtain a Dedicated Buzz Identity

Preferred native-gateway identity:

• dedicated agent nsec and matching npub;
• direct relay membership when a relay administrator can add it; or
• NIP-OA owner attestation when a hosted/closed community uses managed agents.

For Buzz Desktop-managed identities:

1. Have the user create the agent in Buzz Desktop and save the one-time displayed agent nsec locally.
2. Use scripts/update_buzz_credentials.py set-agent-key on the Hermes host. The script prompts locally with hidden input and atomically writes BUZZ_PRIVATE_KEY.
3. Do not assume creating or adding an agent to a channel makes it a direct relay member. Channel membership and relay/community admission differ.
4. If direct authentication returns relay_membership_required and the configured public key exactly matches the Buzz agent, keep the key and proceed to NIP-OA attestation. Do not regenerate identities repeatedly.

Resolve a Python interpreter the user can invoke locally:

• Linux/macOS/WSL: prefer the active Hermes venv Python, then python3.
• Native Windows: prefer %HERMES_HOME%\hermes-agent\venv\Scripts\python.exe, then py -3 or python.

Run the bundled updater from a real local terminal so the user—not the agent chat—enters the secret:

<python> <skill-dir>/scripts/update_buzz_credentials.py set-agent-key --hermes-home <resolved-HERMES_HOME>

Completion criterion: BUZZ_PRIVATE_KEY exists with restricted permissions where supported, but no secret value was printed.

Phase 3: Install the Buzz CLI Portably

Outbound messages always require the external buzz CLI even when inbound WebSocket transport is healthy.

3.1 Prefer a verified prebuilt CLI

1. Query the current stable block/buzz release API.
2. Inspect asset names and content—not just the release title.
3. Use a prebuilt asset only if it is a standalone Buzz CLI matching the exact OS and architecture.
4. Verify its published digest when available, install it to a user-writable path, mark executable on Unix, and run buzz --help.

Desktop .dmg, .deb, .rpm, .AppImage, or Windows desktop installers are not automatically standalone CLI assets.

3.2 Build from a pinned stable release when necessary

Ask approval before downloads or installs. Install prerequisites using the native package mechanism:

Do not hardcode main. Resolve the latest stable release tag from GitHub, show the pinned tag, then clone into a cache/temp build directory:

git clone --depth 1 --branch <stable-tag> https://github.com/block/buzz.git <build-dir>
cargo build --release -p buzz-cli

Install to a user path:

• Linux/macOS/WSL: ~/.local/bin/buzz
• Windows: %USERPROFILE%\.local\bin\buzz.exe

Use the absolute path in Hermes config so service PATH differences cannot break it. On macOS, rerun hermes gateway install --force after adding executables so launchd snapshots the current PATH.

3.3 Build the safe NIP-OA helper

When a hosted managed agent may need owner attestation, copy linked file scripts/hermes_buzz_credential_helper.rs into the pinned Buzz checkout as:

crates/buzz-sdk/examples/hermes_buzz_credential_helper.rs

Build it with the same pinned source:

cargo build --release -p buzz-sdk --example hermes_buzz_credential_helper

Install beside the Buzz CLI as hermes-buzz-credential-helper (append .exe on Windows). This helper reads private input from stdin; never alter it to accept private keys via argv.

Completion criterion: the installed absolute CLI path executes --help; if attestation may be needed, the credential helper also runs and its smoke test with a generated disposable key returns a structurally valid result.

Phase 4: Configure Non-Secret Hermes Settings

Use hermes config set, with the active profile selected when applicable. Set:

gateway.platforms.buzz.enabled = true
gateway.platforms.buzz.extra.relay_url = <relay URL>
gateway.platforms.buzz.extra.cli_path = <absolute CLI path>
gateway.platforms.buzz.extra.channels = [] or explicit UUID list
gateway.platforms.buzz.extra.home_channel = <UUID when outbound cron/notifications are wanted>
gateway.platforms.buzz.extra.poll_interval = 4
gateway.platforms.buzz.extra.require_mention = true
gateway.platforms.buzz.extra.allow_all_users = false
gateway.platforms.buzz.extra.allowed_users = [<owner npub or hex>]
display.platforms.buzz.interim_assistant_messages = false
display.platforms.buzz.tool_progress = off

Use JSON array syntax accepted by the live hermes config set implementation. Verify each value with hermes config get; do not infer success from exit code alone.

Migrate legacy or wizard-created environment-only setups. Environment variables override canonical config, so an old BUZZ_ALLOW_ALL_USERS=true silently defeats allow_all_users: false. After copying every non-secret value into canonical config and verifying it, atomically remove these overrides from the active profile's .env:

BUZZ_RELAY_URL
BUZZ_CHANNELS
BUZZ_HOME_CHANNEL
BUZZ_ALLOWED_USERS
BUZZ_ALLOW_ALL_USERS
BUZZ_POLL_INTERVAL
BUZZ_CLI_PATH
BUZZ_TRANSPORT

Retain credential material such as BUZZ_PRIVATE_KEY, BUZZ_AUTH_TAG, and any documented API token. Before removal, show only variable names and redacted set/unset state; never print values. Restart and re-read effective config after migration.

If the user explicitly wants community-wide invocation, explain that every community member who can address the agent may trigger tools, obtain approval, then set allow_all_users: true. Keep owner/admin command authorization separate.

Completion criterion: canonical non-secret configuration is present, no legacy environment variable overrides it, owner-only access is effective by default, and cli_path is absolute.

Phase 5: Verify Identity and Relay Admission

Load credentials with Hermes' dotenv parser or the bundled updater—not by shell-sourcing .env. Raw BUZZ_AUTH_TAG JSON loses quotation marks when shell-sourced and produces a false invalid JSON diagnosis.

1. Run the helper's public command through the Python updater to derive safe public values from the stored agent key:

<python> update_buzz_credentials.py public --hermes-home <home> --helper <helper-path>

2. Compare the emitted public npub/hex with the agent shown in Buzz.
3. Invoke buzz channels list with the exact dotenv values passed through a subprocess environment.
4. Interpret results:
   • binary missing: fix install path/service PATH;
   • malformed auth tag only after shell sourcing: retest without shell parsing;
   • relay_membership_required plus matching public key: direct membership or NIP-OA is missing;
   • successful auth but zero channels: attach the agent to intended channels;
   • identity mismatch: replace the wrong agent key before doing anything else.

Completion criterion: public identity matches and direct CLI channel discovery succeeds, or the failure is specifically proven to require NIP-OA.