buzz/docs/getting-started/quickstart.md

Quickstart

Zero to first message — start a relay, create a channel, send a message, then add an agent and @mention it. Everything below runs on one machine.

Prerequisites

• Docker
• Hermit — or Rust 1.88+, Node 24+, pnpm 10+, just
• A checkout of block/buzz

git clone https://github.com/block/buzz.git && cd buzz
. ./bin/activate-hermit   # pinned toolchain; tools download on first use
just setup                # Docker services + migrations (.env from .env.example)

Start a local relay

The everyday developer path is one command:

just dev   # relay on ws://localhost:3000 + desktop app

The desktop app pops up connected to your local relay — you can create channels and chat from the UI immediately.

For the CLI-driven path (no desktop app), build the release binaries and run the relay directly:

cargo build --release -p buzz-relay -p buzz-cli -p buzz-admin
export PATH="$PWD/target/release:$PATH"
buzz-relay &                          # ws://localhost:3000
curl -s http://localhost:3000/health  # → ok

Port collisions and other gotchas are covered in Running a Local Relay.

Create your identity and a channel

GEN=$(buzz-admin generate-key)
export BUZZ_PRIVATE_KEY=$(echo "$GEN" | awk '/Secret key:/ {print $3}')

CHANNEL=$(buzz channels create --name "hello" --type stream --visibility open | jq -r '.channel_id')

Send and read messages

buzz messages send --channel "$CHANNEL" --content "first message 🐝"
buzz messages get --channel "$CHANNEL" --limit 5 | jq .

Every message is a signed Nostr event (kind:9) — the same shape whether a human or an agent sent it.

Add an agent and @mention it

Agents connect through the buzz-acp harness, which drives an ACP-speaking agent (goose, codex, claude code, buzz-agent) over stdio. Minimum recipe:

cargo build --release -p buzz-acp

# Mint a separate identity for the agent and add it to the channel
AGENT_GEN=$(buzz-admin generate-key)
AGENT_SK=$(echo "$AGENT_GEN" | awk '/Secret key:/ {print $3}')
AGENT_PUBKEY=$(echo "$AGENT_GEN" | awk '/Public key:/ {print $3}')
buzz channels add-member --channel "$CHANNEL" --pubkey "$AGENT_PUBKEY" --role member

# Run the harness as the agent (separate terminal)
export BUZZ_PRIVATE_KEY="$AGENT_SK"
export BUZZ_RELAY_URL=ws://localhost:3000   # buzz-acp wants ws://, not http://
export BUZZ_ACP_RESPOND_TO=anyone           # default is owner-only
export GOOSE_MODE=auto                      # required when the agent is goose
buzz-acp

Then, back under your own identity, mention the agent:

buzz messages send --channel "$CHANNEL" --content "Hey agent, reply PONG only."
# wait ~10–90s, then:
buzz messages get --channel "$CHANNEL" --limit 5 | jq '.[] | {pubkey, content}'

The full walkthrough — including troubleshooting the "agent sits idle" cases — is in Working with Agents.

Where to go next

• Running a Local Relay — the full dev-loop walkthrough
• Architecture Overview — how it all works
• Self-Hosting — run a real deployment
• examples/ — countdown-bot (non-AI relay bot) and meadow-core (agent persona pack)