Buzz: a signed message bus for your agents

What Buzz is, and what it is not

Buzz is Block's open-source, self-hosted team workspace built on Nostr. The interesting part is not that it does channels and direct messages. It is that an AI agent can hold its own cryptographic key and be a first-class member, posting under an identity nobody can forge.

That single property is what makes it worth the setup effort. Most attempts at agent-to-agent messaging end up with a shared API token, which proves only that the holder had the token. A signed event proves which machine actually spoke.

The honest part first. In our deployment, human-to-human chat is disappointing. Messages routinely took twenty to thirty seconds to arrive, consistently enough that a new user gave up and moved the conversation back to a web forum. That is a deployment observation rather than a verdict on the software, and the Troubleshooting tab explains what we think causes it, but plan around it rather than hoping.

The conclusion we drew, and the reason this guide is framed the way it is: treat Buzz as infrastructure for your agents, not as a chat app for your team. A twenty-second delay is fatal to a human conversation and completely irrelevant to a machine filing a structured report.

Honest scorecard

Genuinely good at

Agents posting under unforgeable identities
A durable, queryable event log you own
Per-key access, revocable without rotating a shared secret
Machine-readable payloads that humans can also read
Running entirely on your own hardware

Not good at, at least for us

Snappy human conversation, see the latency note above
Being another place your team must remember to check
Zero-setup onboarding, every member needs a key
Replacing a forum or an issue tracker

Try the question directly

What do you actually want it for?

Install and connect

Start here, because it catches everyone. A Buzz relay address is not a website. Open it in a browser and you get a page of raw JSON describing the relay's capabilities. That is correct behaviour, not a broken server. You need the desktop app to actually use it.

Get the desktop app
Releases live at github.com/block/buzz/releases. As of 21 August 2026 the current build is v0.5.18, which ships a .dmg for macOS (both Apple Silicon and Intel), .deb and .AppImage for Linux, and an .exe for Windows. Every asset has a matching .sig if you want to verify it.

The Windows build is flagged as an unsigned alpha, so expect a SmartScreen warning.
Get your key from whoever runs the relay
Buzz identities are Nostr keypairs. You need the private half, in bech32 form, which looks like nsec1.... The app's import form accepts nsec1 or ncryptsec1 and will refuse raw hex, which trips people up because most admin tooling emits hex.

Treat it like a password. Anyone holding it can post as you, permanently and unforgeably.
Add the relay
Relay addresses use the websocket scheme, so wss://relay.example.com rather than https://. Use the hostname you were given, not an IP address, for reasons covered in Running a relay.
Import the key and connect
If the relay is in closed mode, which any sensible private deployment is, you will authenticate automatically via NIP-42 and either be admitted or silently rejected.
Check you can see something
If you connect but see no channels at all, you are almost certainly hitting the membership trap on the next tab. It is not you.

Identity and membership

Buzz identity is a Nostr keypair. Your public key is your username, your private key is your password, and every message you send is signed with it. Nobody can post as you without your key, and an administrator can revoke you by key without disturbing anyone else.

The trap that cost us an afternoon. There are two independent membership lists, and adding somebody to one does not add them to the other. Worse, the failure is completely silent: the channel command reports success, and the person simply cannot connect, with no error explaining why.

List	Controls	Managed with
Relay membership	Whether this key may connect to the relay at all. On a closed relay, a key that is missing here is refused during authentication, before any channel logic runs.	The server-side admin binary, `buzz-admin add-member`
Channel membership	Which rooms you can see once you are connected.	The client CLI, `buzz channels add-member`

So onboarding anybody, human or agent, is always two commands:

# 1. let them onto the relay at all (run on the relay host)
buzz-admin add-member --pubkey <hex-or-npub> --role member

# 2. let them see a specific room
buzz channels add-member --channel <channel-uuid> --pubkey <hex>

Miss the first and your new member sees nothing, gets no useful error, and reports that "it isn't working". Miss the second and they connect fine but the room they were invited to is invisible.

Diagnosing it: if the relay's own logs show a successful NIP-42 authentication for their key, relay membership is fine and the problem is channel membership. If there is no authentication line at all, they never got through the front door.

Why signed identity is worth the friction

Every message carries provable authorship, so a report filed by a particular machine is attributable to that machine forever. Compare a shared bearer token, where any leak is indistinguishable from legitimate use and the only remedy is rotating the secret for everybody at once. Here you delete one key.

Running your own relay

Buzz self-hosts as a small Docker Compose stack. The official repository carries the canonical deployment instructions; what follows is the operational knowledge that is not obvious until it bites you.

What the stack actually is

Service	Role
relay	The Buzz relay itself, from the project's published container image
postgres	Event and membership storage. This is your system of record
redis	Live fan-out to connected clients
minio	Object storage for file attachments

Pin the relay image by digest rather than floating on a tag. An unattended pull that changes your relay's behaviour is a bad afternoon.

Docker port publishing bypasses your host firewall. If you publish the relay as 3300:3000 it binds 0.0.0.0 and is reachable from the internet, whatever your iptables rules say, because Docker inserts its own rules ahead of yours. Bind explicitly to a private interface instead, as in <private-ip>:3300:3000, and put a reverse proxy in front for public access. Then actually probe the public IP on that port and confirm it refuses.

The host header trap

This one is worth reading twice, because it is architectural rather than a misconfiguration.

The relay treats an unfamiliar Host header as a brand new tenant and creates a fresh, empty community for it. A channel's community binding is immutable once created, so there is no rebinding or aliasing after the fact.

The practical consequence: if you set the relay up on an internal address and later expose it under a public hostname, the public hostname opens onto an entirely empty workspace while all your real data remains attached to the internal one. We had to wipe and rebuild the pilot from scratch to fix it.

So decide your permanent public hostname before you create a single channel, and from then on address the relay only by that hostname. Never by raw IP, except for an unauthenticated health check, which does not resolve a tenant.

Administering it

# run inside the relay container
buzz-admin add-member --pubkey <hex-or-npub> --role member
buzz-admin remove-member --pubkey <hex-or-npub>
buzz-admin list-members
buzz-admin generate-key            # new keypair, prints hex
buzz-admin migrate                 # pending DB migrations

generate-key emits raw hex, but desktop clients want nsec1 bech32. You will need a small conversion step in between. Generate keys on the server and never let the private half touch a chat message or a shell history.

Fronting it with a reverse proxy

Websockets need explicit upgrade handling and generous timeouts. In nginx terms, that means passing Upgrade and Connection through, setting long read and send timeouts, and turning proxy buffering off. Miss those and connections drop in ways that look like application bugs.

Using it with agents

This is what Buzz is genuinely for, and where the latency that ruins human chat simply does not matter.

Give the agent its own key

Resist the temptation to let an agent post under your identity. A separate key means you can see exactly what the machine said as distinct from what you said, and you can revoke the machine without locking yourself out. Add it to the relay and to only the channels it needs.

Structure the payload, do not just chat

A room full of free-text agent output is expensive to triage and impossible to count. Give the messages a fixed shape instead, and you can dedupe, aggregate and query them.

The pattern we settled on serves humans and machines from one message: a readable summary line, then a fenced JSON block holding the real payload.

**[bug / major]** Widget save silently drops zero values
App 2.1 · PHP 8.3 · nginx

```json
{ "spec": "your-spec/1", "category": "bug", "severity": "major", ... }
```

Anyone scrolling the channel reads the summary. A consumer reads the fenced block and ignores everything else, which conveniently means humans can still talk in the room without confusing the machines.

Keep a human gate. An agent that can publish unattended into a shared room will eventually publish something you would not have. Debug output carries hostnames, file paths, and whatever was in the log. Make the agent scrub first, then show you the exact payload, then wait for a yes. Signed messages are effectively permanent; deletion in Nostr is a request, not an erasure.

Posting from a server, on any platform

The official CLI is a macOS binary. If your agent runs on a Linux server, as most do, it cannot use it. This caught our first outside tester, whose server-side agent could not post at all, reducing the whole thing to copying and pasting by hand.

The route that works everywhere is the relay's own HTTP bridge, which is what the desktop client uses under the covers. Two endpoints do everything an agent needs:

Endpoint	Does	Body
`POST /events`	Publishes a message	The signed event, bare at the top level
`POST /query`	Reads events	An array of Nostr filters

Both authenticate with NIP-98: a short-lived, signed event carried in the Authorization header, proving which key is making the call.

Three things that will bite you

Give your NIP-98 auth event a nonce
Its timestamp has one-second resolution, so two calls in the same second produce byte-identical auth events with the same id, and the relay correctly rejects the second as a replay. Add a random tag so each one is unique.
Set a real User-Agent
Default agent strings from scripting languages trip bot protection on some CDNs. That surfaces as an opaque 403 that looks exactly like an authentication failure, except the request never reached the relay at all.
Send the event bare, not wrapped
POST /events wants the signed event object itself as the body. Wrapping it in an outer object gets you a confusing complaint about a missing id field.

Signing is BIP-340 Schnorr over secp256k1. That sounds like a dependency, but it is about eighty lines of arithmetic and can be done with nothing but a standard library, which matters when the whole point is that an agent on somebody else's server can participate without a build step.

A working client, if you would rather not write one. Python 3, standard library only, no pip install and no build step. It signs, handles all three traps above, and posts a structured report to a channel. Point it at your own relay with three environment variables.

Download post-report.py

# check it can authenticate before trusting it with anything
export BUZZ_RELAY_URL=https://relay.example.com
export BUZZ_PRIVATE_KEY=nsec1...        # or 64-char hex
export BUZZ_CHANNEL=<channel-uuid>

python3 post-report.py --check          # prints your pubkey, does a real round trip
python3 post-report.py --search zero    # check for an existing twin BEFORE filing
cat report.json | python3 post-report.py --dry-run   # shows what would be sent
cat report.json | python3 post-report.py             # signs and publishes

--search is not a convenience. Two steps of the filing discipline need reads: checking whether your finding already exists, so your sighting groups onto it instead of silently splitting it in two, and confirming what came back afterwards. A client that can only write cannot follow its own rules.

Verify the checksum on any key you accept. A mistyped bech32 key does not fail to decode. It decodes to a different, perfectly valid key, which signs perfectly valid events as an identity that is not a member of anything. The relay then rejects it as unauthorised, so the error points at membership while the real fault is a typo six characters earlier. Check the checksum and the prefix, and say "mistyped" rather than letting the relay say "unauthorised".

Consuming the room

POST /query is enough for an agent to check what already exists before adding to it. For anything heavier, run an indexer alongside the relay that reads the channel, validates the shape, and writes to a database you control. The relay stays the system of record; the index is what makes it answerable.

If you index, handle edits. An edit is not a modified message. It is a new event of a different kind carrying a reference to the original, so an indexer filtering on message kind alone will silently ignore every correction and keep serving superseded text. Ours did exactly that until a tester revised a report and we noticed the board had not moved. Resolve the reference and update the original record in place, so a correction can never be mistaken for a second occurrence.

We describe one worked example of the whole pattern, including deduplication and sighting counts, in Field reports your agent can act on.

Troubleshooting

Every symptom below is one we actually hit. Pick the one that matches.

What is happening?

The latency problem, in detail

Our symptom was human messages taking twenty to thirty seconds, consistently, in both directions. Resource use ruled out load: the relay sat at around two per cent CPU and a twentieth of its memory limit, with the database and cache idle.

What the logs did show was connection churn. Clients authenticated successfully, then were dropped with a "missed pongs" warning, then reconnected. Messages sent across a reconnect cycle surface late and in bursts, which is exactly what a twenty-second delay feels like from the outside.

Our leading suspect is the CDN proxy in front of the relay interfering with websocket keepalive frames. If you are seeing the same thing, the things worth testing in order:

Connect directly to the origin, bypassing any CDN, and see whether the delay disappears. This isolates the proxy immediately.
Check your CDN actually has websocket support enabled, and look for an idle timeout shorter than the relay's ping interval.
Check the reverse proxy passes upgrade headers and has long read and send timeouts with buffering off.

Until it is solved, design around it. Use Buzz for agent traffic where a delay of seconds is irrelevant, and keep human conversation somewhere it is not.

FAQ

Is Buzz a hosted service I can sign up for?

No. It is open source software you run yourself. That is the point, and it is also the cost: you own the hosting, the upgrades and the keys.

Do I need to understand Nostr to use it?

To use it as a member, no. You need a key and a relay address. To run it, a working understanding helps a great deal, particularly around signed events, relay authentication, and the fact that deletion is a request rather than a guarantee.

Can I use it as an issue tracker or a forum?

We would not. A forum is better at threaded human discussion and needs no install; an issue tracker is better at state. Buzz earns its place when you want signed machine traffic in a place you control, which neither of those gives you.

What happens if someone's key leaks?

Remove that key from relay membership and issue a new one. Nothing else is affected, which is the advantage over a shared token. Anything already signed with the leaked key stays signed, so treat a leak as a disclosure question as well as an access one.

Is it worth the setup effort?

If you want provable identity for machine traffic on infrastructure you own, yes, and there is not much else that does this. If you want your team to chat, almost certainly not.