Task 3.2 · 2 of 7

Connect a Hermes agent to a Buzz community

Workspace owner, technical support · Build the agent team

Why this matters

Hermes can run shell commands and use credentials on its host. A Buzz Desktop or relay-bridge connection uses ACP, where permission requests may be approved without a person seeing a prompt. Keep these connections owner-only unless you have deliberately narrowed the host, tools and author allowlist. The native gateway keeps Hermes' own approval system, but it still holds an agent private key and must be scoped explicitly.

Steps at a glance

Choose how Hermes will participate
Get Hermes working before connecting Buzz
Give the agent a dedicated identity and channel scope
Connect Hermes using the chosen path
Restrict who can prompt the agent
Set what reaches the channels
Test the connection and its boundaries
Make ownership and recovery operational

Validate before publication

A wrong choice here can expose the Hermes host or its Nostr identity. The procedure is based on the Hermes and Buzz upstream documentation and still needs an end-to-end practitioner pass against the target community. Validate with a disposable agent identity before connecting a working Hermes profile.

Not yet verified

Four things in this page are taken from documentation rather than from a running build: the Settings → Runtimes path, the Who can talk to this agent control and its Owner only value, the hermes-acp binary name, and hermes acp --check. Check each against your build before you follow it as a click path; the labels are the part most likely to have moved.

1. Choose how Hermes will participate

Hermes and Buzz support three different relationships. Choose one from the outcome you need, not from which configuration looks shortest.

Path	Choose it when	Who runs and controls Hermes
Buzz Desktop runtime	You are exploring Hermes locally and want Buzz to create and launch the agent	Buzz Desktop starts Hermes over ACP on the desktop machine
Relay bridge	You want a hosted agent identity while Buzz owns the channel transport	`buzz-acp` connects the relay to a Hermes ACP subprocess, normally under a service manager
Native gateway	Hermes already exists as an agent and Buzz should become another place where people can reach it	The independently operated Hermes gateway joins the community as a Nostr member

The native gateway is the deepest integration. Hermes keeps its own memory, skills, approvals, sessions and scheduled work while Buzz supplies the shared channels. It is not a Buzz-managed runtime: Buzz Desktop does not start, stop or fully observe it. See Hermes agents in Buzz.

Do not make one identity serve two paths. Give the chosen deployment its own identity so there is one clear operator and one process signing as that agent.

2. Get Hermes working before connecting Buzz

Install Hermes and configure its model provider using the Hermes setup flow:

hermes setup

Complete a normal conversation outside Buzz. Do not add the gateway or relay bridge until Hermes can answer and use the tools you intend it to have.

For either ACP path, verify the ACP adapter as well:

hermes acp --check

Decide which operating-system account will run Hermes. That account's files, credentials, skills and executable tools define the agent's reach beyond Buzz.

3. Give the agent a dedicated identity and channel scope

The Desktop-runtime path lets Buzz create and manage the agent identity. For the relay bridge or native gateway, create a dedicated Nostr keypair, register its public key as a member of the community, and add it only to the channels where it should work.

Never reuse a human private key. The agent's private key is both its identity and its signing authority; anyone who obtains it can act as that agent.

Store the private key in the secret store used by the selected path:

Native gateway: BUZZ_PRIVATE_KEY in ~/.hermes/.env.
Relay bridge: BUZZ_PRIVATE_KEY in the protected service environment.
Desktop runtime: Buzz manages the agent identity; do not paste your own human key into the runtime configuration.

Record the public key, owner, host and permitted channels in the team's agent register. See Agent ownership and the trust chain.

4. Connect Hermes using the chosen path

Buzz Desktop runtimeRelay bridgeNative gateway

Open Settings → Runtimes. Hermes Agent should appear when hermes-acp is available on the login-shell path.

If it does not appear, check:

command -v hermes-acp || command -v hermes

Update Hermes if an older installation lacks the hermes-acp launcher. As a manual fallback, register hermes with the argument acp.

Create the Buzz agent, select the Hermes runtime, and leave Who can talk to this agent set to Owner only.

Build buzz-acp and the buzz CLI from the Buzz repository, then run the bridge as the same operating-system user that owns the intended Hermes home.

Configure its protected service environment:

BUZZ_RELAY_URL="wss://community.example.com"
BUZZ_PRIVATE_KEY="<dedicated-agent-secret>"
BUZZ_ACP_AGENT_OWNER="<owner-hex-pubkey>"
BUZZ_ACP_AGENT_COMMAND="hermes"
BUZZ_ACP_AGENT_ARGS="acp"
BUZZ_ACP_RESPOND_TO="owner-only"

Add BUZZ_API_TOKEN only when the relay requires token authentication. Start buzz-acp under the service manager. The bridge discovers channels from the agent's memberships and subscribes when the identity is added to another channel.

Put the buzz CLI on the Hermes host's path, or record its location as BUZZ_CLI_PATH. Then run:

hermes gateway setup

Choose Buzz and complete the guided setup. The equivalent explicit configuration is:

gateway:
  platforms:
    buzz:
      enabled: true
      extra:
        relay_url: https://community.example.com
        channels:
          - <channel-uuid>
        home_channel: <channel-uuid>
        allowed_users:
          - <owner-npub-or-hex-pubkey>
        allow_all_users: false
        require_mention: true
        transport: auto

Keep the secret outside config.yaml:

BUZZ_PRIVATE_KEY=nsec1...

With transport: auto, inbound messages normally arrive through an authenticated Nostr WebSocket and fall back to polling if that connection cannot be established; websocket requires the WebSocket and fails otherwise, poll uses polling only. Outbound messages use the Buzz CLI. (Both Hermes pages now describe delivery this way — re-checked 2026-09-02; an earlier polling-only description has gone.)

5. Restrict who can prompt the agent

Apply the secure default for the chosen path before testing:

Path	Secure starting point
Desktop runtime	Owner only in the agent's Buzz settings
Relay bridge	Set `BUZZ_ACP_AGENT_OWNER` and keep `BUZZ_ACP_RESPOND_TO=owner-only`; use an explicit hex-pubkey allowlist only when a named team needs access
Native gateway	Keep `allow_all_users: false`, list permitted npubs or hex pubkeys under `allowed_users`, and require mentions in channels

Channel membership and author permission answer different questions. Membership determines where the agent can read and post; the author gate determines whose request it will execute. Configure both.

Do not change an ACP-connected Hermes agent to Anyone merely to make a failed test respond. Diagnose its owner, membership and runtime first.

6. Set what reaches the channels

For the native gateway, name the watched channels instead of accepting every joined channel, and set one home channel for scheduled results and notifications.

Keep internal execution noise out of the shared conversation:

display:
  platforms:
    buzz:
      interim_assistant_messages: false
      tool_progress: off

In shared channels, keep require_mention: true so ordinary conversation does not become work for the agent. Direct messages are still direct requests, subject to the configured author allowlist.

For the relay bridge, channel membership supplies the scope. For the Desktop runtime, add the agent only to the channels it needs.

7. Test the connection and its boundaries

Start the selected runtime. For the native gateway:

hermes gateway start
hermes gateway status

Run a controlled acceptance test:

The owner mentions the agent in an allowed channel and receives one final response.
An allowed teammate receives a response only if the design includes them.
A non-allowed member cannot trigger work.
A message without a mention does not trigger the agent in a shared channel.
The response is signed by the dedicated agent identity.
The agent cannot read or post in a channel it has not joined.
If scheduled delivery is required, a test job reaches the configured home channel.

Check the control surface for the selected path. Buzz Desktop shows its managed agent. A relay bridge can publish owner-only observer activity when configured. A native gateway is operated through Hermes status and logs rather than Buzz's runtime controls.

8. Make ownership and recovery operational

For a persistent bridge or native gateway, run the process under a service manager and a dedicated operating-system account. Restrict access to the Hermes home and service environment.

Document:

who owns the agent and approves new users or channels;
where the gateway or bridge runs;
how to stop and restart it;
where its public identity is recorded and its private key is protected;
how the key, provider credentials and external-system grants are revoked;
which Hermes state must be backed up if its private memory and sessions need to survive a host loss.

Test shutdown before treating the agent as operational. Desktop agents use the Buzz runtime controls; a relay-bridge owner can use its documented !cancel, !rotate and !shutdown controls; the native gateway is stopped at its Hermes service.

Verified against Buzz v0.5.20 · Updated 2 Sep 2026