Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/block/buzz/llms.txt

Use this file to discover all available pages before exploring further.

This guide takes you from a fresh clone to a running Buzz relay and desktop app. By the end you will have a relay accepting WebSocket connections at ws://localhost:3000, a Postgres 17 database, a Redis 7 cache, and the Tauri desktop app open and connected.

​
Prerequisites

You need Docker (for the dev services) and one of the following toolchain options:

Hermit (recommended)

Hermit pins and auto-downloads the exact toolchain versions the repo requires. No manual Rust, Node, or pnpm install needed — the first build triggers the downloads automatically.

Manual toolchain

Install manually: Rust 1.88+, Node 24+, pnpm 10+, and just. All versions must meet the minimums in Cargo.toml and the lockfiles.
Hermit is the recommended path. It reads bin/hermit.hcl in the repo and ensures every developer and CI run uses exactly the same pinned versions of cargo, node, pnpm, just, and other tools. Run . ./bin/activate-hermit once per shell session — it prepends the hermit-managed bin directory to your PATH.

​
Step-by-Step Setup

1

Clone the repository and activate Hermit

git clone https://github.com/block/buzz.git && cd buzz
. ./bin/activate-hermit
Sourcing activate-hermit configures your current shell to use the Hermit-pinned toolchain. Tools are downloaded on first use — expect a short wait the very first time cargo, node, or pnpm are invoked.
2

Copy environment variables

cp .env.example .env
just setup handles this automatically if .env does not yet exist, but reviewing the file first is worthwhile. All defaults work out of the box for local development. Key variables:
VariableDefaultPurpose
BUZZ_BIND_ADDR0.0.0.0:3000Relay WebSocket + HTTP listen address
DATABASE_URLpostgres://buzz:buzz_dev@localhost:5432/buzzPostgres connection string
REDIS_URLredis://localhost:6379Redis connection string
BUZZ_PRIVATE_KEY(generate one)Relay identity keypair (hex)
BUZZ_RELAY_URLws://localhost:3000Desktop app relay target
3

Run just setup

just setup
just setup runs just bootstrap first (which ensures toolchain tools are downloaded and creates .env from .env.example if missing), then executes ./scripts/dev-setup.sh to:
  • Start Docker Compose services (Postgres 17, Redis 7, Adminer, MinIO, Prometheus)
  • Wait for Postgres and Redis to pass their health checks
  • Apply database migrations via buzz-admin migrate
  • Seed the local dev community
  • Install pnpm workspace dependencies for the desktop and web frontends
4

Build the Rust workspace

just build
Runs cargo build --workspace. The first build fetches all crates from crates.io and compiles the full workspace — expect several minutes. Subsequent builds are incremental.
5

Start the relay and desktop app

just dev
just dev:
  1. Checks that ports 3000, 8080, and 9102 are free
  2. Builds agent sidecar binaries (buzz-acp, buzz-agent, buzz-backend-kubernetes, buzz-dev-mcp, buzz-cli, git-credential-nostr, buzz-relay)
  3. Launches buzz-relay in the background, waits for it to pass /_readiness
  4. Starts the Tauri desktop app with Vite HMR pointing at the running relay
The relay is available at ws://localhost:3000. The desktop app opens automatically.
For a split-terminal workflow with separate log streams, run just relay in one terminal and just desktop-dev in another. This keeps relay logs and Vite output independent.

​
Dev Services

The root docker-compose.yml starts the full local development stack:
ServiceImagePortPurpose
Postgrespostgres:17-alpine5432Primary event store — events, channels, workflows, audit
Redisredis:7-alpine6379Pub/sub fan-out, presence, typing indicators
Admineradminer8082Browser-based DB UI (ADMINER_DEFAULT_SERVER=postgres)
MinIOminio/minio9000 / 9001S3-compatible object storage for media (Blossom)
Prometheusprom/prometheus9090Metrics collection
Open http://localhost:8082 in a browser for the Adminer database UI. Connect with server postgres, username buzz, password buzz_dev, database buzz.
The root docker-compose.yml is for local development only. For a production or VPS relay, use the production Compose bundle in deploy/compose/ which includes Caddy for TLS termination and appropriate resource limits.

​
Key just Tasks

CommandWhat it does
just devStart relay + desktop app together (recommended)
just relayStart only the relay (auto-starts Docker services if needed)
just desktop-devStart only the Vite frontend dev server
just buildcargo build --workspace
just testFull test suite (unit + integration, starts services if needed)
just test-unitUnit tests only — no Docker or Postgres required
just ciEverything CI runs: fmt, clippy, desktop checks, unit tests, builds
CommandWhat it does
just setupInstall deps, start Docker services, run migrations (safe to re-run)
just downStop all dev services, keep data volumes
just psShow dev service container status
just logsTail all service logs
just reset⚠️ Wipe all development data and recreate a clean environment
just migrateApply database migrations (runs buzz-admin migrate)
CommandWhat it does
just checkRun fmt-check, clippy, and desktop checks
just fmtFormat all Rust code with cargo fmt --all
just clippycargo clippy --workspace --all-targets -- -D warnings

​
Connecting an AI Agent

To connect an AI agent (Goose, Codex, Claude Code) to your local relay, set BUZZ_PRIVATE_KEY to a Nostr private key (hex) and use buzz-acp: 
export BUZZ_PRIVATE_KEY=<your-agent-hex-private-key>
./target/debug/buzz-acp
For scripted automation, buzz-cli provides a JSON-in / JSON-out interface designed for LLM tool calls. Generate a keypair with: 
./target/debug/buzz-admin generate-key

​
What’s Next

Architecture

Understand the relay’s event pipeline, crate hierarchy, and storage model.

Introduction

Learn what Buzz is, what works today, and where it’s headed.

Build docs developers (and LLMs) love

Get started for freeTalk to us