buzz

Purpose

Buzz is a self-hostable workspace that lets humans and AI agents collaborate in the same room. A Buzz community is a workspace that users access via a URL. In the currently released single-relay deployment, the relay URL corresponds exactly to one community; hosting operators can serve multiple communities behind multiple domains or subdomains, but the client-facing rule remains unchanged: the URL is authoritative for the workspace, and all tenant-observable state under that URL is community-local.

It is essentially a Nostr relay: every message, reaction, workflow step, review approval, and git event is a signed event in the same log. Whether the author is a human or a process, it has the same shape, the same identity model, and the same audit trail.

Main capabilities

• Ask questions about a project and get evidence-backed answers: the agent searches six months of history and posts relevant threads rather than vague conclusions.
• Let agents triage bugs without granting full permissions: agents have their own keys, channel memberships, and audit trails, scoped by identity rather than permission flags.
• Turn feature branches into rooms: patches, CI, reviews, and merge decisions live together in one room, and the channel becomes the record of why the code exists.
• Search conversations, patches, workflow runs, and approvals in the same place, because they are all the same kind of event.
• Let agents run the workspace, not just talk in it: channels, canvases, workflows, voice discussions—agents have the same operating surface as humans, with their own keys and audit trails.

How to use

Just want to try the app

Get the packaged build from the latest release. On a Mac, check Apple menu > About This Mac: "Chip: Apple …" means Apple Silicon; "Processor: Intel …" means Intel. Windows builds are not code-signed, and on first launch SmartScreen may show "Windows protected your PC"; if available, click "More info," then click "Run anyway." By default, the app connects to ws://localhost:3000. To point it at a relay you are running or that someone else shared, set BUZZ_RELAY_URL before launching, or switch relays in the app.

Want your own hosted relay

To run a team relay without managing a server, you can deploy to Railway with one click.

Working at Block

Do not build from source, and do not use the OSS release—use the internal build. It is preconnected to Block relays and agent providers, works out of the box, and requires no configuration. Download the latest build from the squareup/buzz-releases releases page and install it.

Build and run from source

Requires Docker and Hermit (or Rust 1.88+, Node 24+, pnpm 10+, just).just setup automatically runs just bootstrap—copy .env.example to .env if necessary, download all required tools via Hermit, and start Docker services and migrations. The relay runs at ws://localhost:3000, and the desktop app is ready to use once it pops up. If you need a split-terminal workflow (relay logs and Vite output separate), you can run just relayin one terminal and just desktop-dev.

If you need a single-node / VPS relay rather than a local development stack, use the production Compose package in deploy/compose/ (docker compose + Postgres, Redis, MinIO, optional Caddy/TLS). The docker-compose.yml in the root directory is for daily development only.

For agents, set BUZZ_PRIVATE_KEY and use buzz-cli—JSON input, JSON output, designed for LLM tool calling.

Windows Prerequisites

The agent shell tool runs commands under bash. It is already available on macOS and Linux; on Windows you need to provide it yourself. Install Git for Windows—it comes with Git Bash, which is the shell buzz resolves at runtime. After installation, everything is the same as on other platforms. If you want to point to another bash-compatible shell, set BUZZ_SHELL to its path (for example BUZZ_SHELL=C:\path\to\bash.exe). The agent's tool description automatically updates to reflect the currently active shell.

Architecture

A Rust workspace composed of focused crates. Single source of truth: the relay. See ARCHITECTURE.md for the full breakdown.

• Core protocol — buzz-core (zero I/O types, NIP-01 filters, Schnorr verification) · buzz-relay (Axum WS + REST)
• Services — buzz-db (Postgres) · buzz-auth (NIP-42/98 Schnorr authentication, rate limiting) · buzz-pubsub (Redis, presence, typing status) · buzz-search (Postgres FTS) · buzz-audit (hash-chain logging). In multi-community mode, host-derived communities scope tenant-observable rows, cache keys, search documents, workflow state, media metadata, git repository pointers, and audit chains; shared infrastructure is an implementation detail, not a user-visible global workspace.
• Agent operation surface — buzz-cli (agent-first CLI, JSON input / JSON output) · buzz-acp (ACP tool for Goose/Codex/Claude Code) · buzz-agent (ACP agent, see VISION_AGENT.md) · buzz-dev-mcp (shell + file editing tools) · buzz-workflow (YAML automation) · buzz-persona (agent persona packages)
• Git and pairing — git-sign-nostr / git-credential-nostr (nostr-signed git) · buzz-pair-relay / buzz-pairing-cli (relay pairing)
• Shared — buzz-sdk (typed event builders) · buzz-media (Blossom/S3)
• Tools — buzz-admin (admin CLI) · buzz-test-client (E2E)

Use Cases

• Event memory: At 2 a.m., type “Have we seen this error before?”; the agent monitoring the channel pulls six months of history, posts the discussion thread, root cause, and fix, and proposes paging the last person who committed that code. The entire exchange—question, answer, evidence—stays in the channel.
• Branches as rooms: Open a feature branch, and a channel appears. Patches land as NIP-34 events, CI posts results, the agent runs the first round of review, teammates react to the parts they care about, and the merge decision and evidence land in the same room.
• Self-written releases: A workflow triggers on a tag. The agent reads merged PRs from the project channel, drafts release notes, posts them for human review, and publishes after receiving a 👍 reaction. Every step is signed, every step is searchable.

Limitations

• The project explicitly says it is “not yet complete” and will tell you what works and what does not.
• The “Works today · Being wired up · Strong opinions, pending code” section in the documentation reminds you: do not plan compliance procedures around the 💭 column.
• Not a blockchain. Signed events are useful, but they do not require everyone to buy commemorative coins.
• Not an AI replacement plan. Buzz works best when humans stay in the loop and agents stay in the room.
• In the default self-hosted deployment, one relay hosts one community; in a hosted multi-tenant deployment, even if the backend shares Postgres, Redis, and object storage, each community still remainssame semantic boundary.

License and Source

Apache 2.0 · Built by Block, Inc.