mirror of
https://github.com/block/buzz.git
synced 2026-11-03 07:51:22 +00:00
23f75dac90
Fill all 31 stub pages scaffolded in Phase 1 with content migrated and verified from the root docs, crate READMEs, and source code: - getting-started/ (3): installation, quickstart, local relay (TESTING.md) - architecture/ (8): ARCHITECTURE.md §1–§8, one page per section - guides/ (9): development, testing, agents, workflows, self-hosting, nostr-clients (operational half of NOSTR.md), adding-event-kinds, adding-api-endpoints, releasing - reference/ (5): CLI reference verified against buzz --help and crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted), configuration, known-limitations (ARCHITECTURE §9 + conformance LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical), design-docs index - vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational banners and rewritten links Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get pointer notes marking docs/ as canonical; deletion is a follow-up. All relative links in the new tree verified to resolve. Known limitations are documented honestly, never papered over: rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README drift, one-line GOVERNANCE.md. Note: pre-commit sadscan findings reviewed as false positives (dev-default postgres URI and NIP-OA test vectors, both already on origin/main). Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# 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)
|