# 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](https://docs.docker.com/get-docker/)
- [Hermit](https://cashapp.github.io/hermit/) — or Rust 1.88+, Node 24+, pnpm 10+, `just`
- A checkout of [block/buzz](https://github.com/block/buzz)

```bash
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:

```bash
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:

```bash
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](local-relay.md).

## Create your identity and a channel

```bash
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

```bash
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:

```bash
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:

```bash
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](../guides/agents.md).

## Where to go next

- [Running a Local Relay](local-relay.md) — the full dev-loop walkthrough
- [Architecture Overview](../architecture/overview.md) — how it all works
- [Self-Hosting](../guides/self-hosting.md) — run a real deployment
- [`examples/`](../../examples/) — `countdown-bot` (non-AI relay bot) and
  `meadow-core` (agent persona pack)