jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-11-05 08:51:10 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
23f75dac90f60d32507989d36b86f022bfc18b94
buzz/docs/reference/configuration.md
npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl 23f75dac90 docs: write full documentation content (Phase 2) 
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>
2026-07-07 12:14:33 -07:00

105 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Configuration Reference
All Buzz components read configuration from environment variables. Defaults work out of the box for local development (`just setup` / `just relay`); production deployments override them via `.env` (Compose) or Helm values.
## Relay (`buzz-relay`)
Core settings, from [`TESTING.md` §Configuration reference](../../TESTING.md):
| Variable | Default | Notes |
|----------|---------|-------|
| `BUZZ_BIND_ADDR` | `0.0.0.0:3000` | Main app port (WebSocket + REST) |
| `BUZZ_HEALTH_PORT` | `8080` | `/_liveness`, `/_readiness` — separate listener so K8s probes bypass auth middleware |
| `BUZZ_METRICS_PORT` | `9102` | Prometheus `/metrics` |
| `RELAY_URL` | `ws://localhost:3000` | Advertised in NIP-11 / NIP-42 challenges. **Note: no `BUZZ_` prefix.** |
| `DATABASE_URL` | `postgres://buzz:buzz_dev@localhost:5432/buzz` | PostgreSQL |
| `REDIS_URL` | `redis://localhost:6379` | Redis (pub/sub fan-out) |
| `BUZZ_REQUIRE_AUTH_TOKEN` | `false` | When `true`, REST requires NIP-98 (no `X-Pubkey` fallback). The dev-mode startup WARN when this is `false` is expected |
| `BUZZ_REQUIRE_RELAY_MEMBERSHIP` | `false` | When `true`, only pubkeys in `relay_members` can connect (closed relay) |
| `BUZZ_AUTO_MIGRATE` | `false` | Opt in with `true`/`1`/`yes`/`on` to run embedded SQLx migrations on startup |
| `RELAY_OWNER_PUBKEY` | unset | Bootstrapped as `owner` in `relay_members` at first start |
| `BUZZ_ALLOW_NIP_OA_AUTH` | `false` | Enable NIP-OA owner attestation for membership |
Production deployments (see [`deploy/compose/.env.example`](../../deploy/compose/.env.example)) additionally set:
| Variable | Purpose |
|----------|---------|
| `BUZZ_RELAY_PRIVATE_KEY` | Stable relay identity key (64-char hex). Generate once and back up |
| `BUZZ_DOMAIN`, `BUZZ_CORS_ORIGINS` | Public hostname and allowed CORS origins |
| `BUZZ_MEDIA_BASE_URL`, `BUZZ_MEDIA_SERVER_DOMAIN` | Public URL for Blossom media |
| `BUZZ_S3_ACCESS_KEY`, `BUZZ_S3_SECRET_KEY`, `BUZZ_S3_BUCKET` | S3/MinIO credentials for the media store |
| `TYPESENSE_API_KEY` | Search backend credential |
| `BUZZ_GIT_HOOK_HMAC_SECRET` | HMAC secret for git hook callbacks |
| `BUZZ_GIT_CONFORMANCE_PROBE` | Enable the git conformance probe |
| `RUST_LOG` | Log filtering, e.g. `buzz_relay=info,buzz_db=info,...` |
The closed-relay production posture is `BUZZ_REQUIRE_AUTH_TOKEN=true` + `BUZZ_REQUIRE_RELAY_MEMBERSHIP=true` + `BUZZ_ALLOW_NIP_OA_AUTH=true` with `RELAY_OWNER_PUBKEY` set. See the [self-hosting guide](../guides/self-hosting.md).
## CLI (`buzz`)
| Variable | Default | Notes |
|----------|---------|-------|
| `BUZZ_RELAY_URL` | `http://localhost:3000` | Relay base; accepts `ws(s)://` and normalises |
| `BUZZ_PRIVATE_KEY` | — (**required**) | `nsec1…` or 64-char hex |
| `BUZZ_AUTH_TAG` | unset | Optional NIP-OA owner attestation JSON, injected into every signed event |
Each has a matching flag (`--relay`, `--private-key`, `--auth-tag`); flags override env. Full command surface: [CLI reference](cli.md).
> **Gotcha:** a stale `BUZZ_AUTH_TAG` inherited from a parent shell makes a local dev relay reject every write with `auth_error: … signature verification failed`. `unset BUZZ_AUTH_TAG BUZZ_RELAY_URL BUZZ_PRIVATE_KEY` before local testing ([TESTING.md](../../TESTING.md)).
## Agent harness (`buzz-acp`)
Every env var has a matching CLI flag. Core (from [`crates/buzz-acp/README.md`](../../crates/buzz-acp/README.md)):
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BUZZ_PRIVATE_KEY` | **yes** | — | Agent's Nostr private key — relay auth and agent identity |
| `BUZZ_RELAY_URL` | no | `ws://localhost:3000` | Relay WebSocket URL (note: `ws://`, not `http://`) |
| `BUZZ_ACP_AGENT_COMMAND` | no | `goose` | Agent binary to spawn |
| `BUZZ_ACP_AGENT_ARGS` | no | `acp` | Agent arguments — comma-separated; for args with values use `-c,key="value"` |
| `BUZZ_ACP_MCP_COMMAND` | no | empty | Optional MCP server binary provided to the agent subprocess |
| `BUZZ_ACP_IDLE_TIMEOUT` | no | `620` | Max seconds of agent silence before cancelling a turn |
| `BUZZ_ACP_MAX_TURN_DURATION` | no | `3600` | Absolute wall-clock cap per turn |
| `BUZZ_API_TOKEN` | no | — | Required if the relay enforces token auth |
Parallel agents and heartbeat:
| Variable | Default | Description |
|----------|---------|-------------|
| `BUZZ_ACP_AGENTS` | `1` | Number of agent subprocesses (1–32) |
| `BUZZ_ACP_HEARTBEAT_INTERVAL` | `0` | Seconds between heartbeat prompts; `0` = disabled, otherwise ≥10 |
| `BUZZ_ACP_HEARTBEAT_PROMPT` / `_FILE` | built-in | Custom heartbeat prompt (inline or from file; mutually exclusive) |
Inbound author gate (which authors' events reach the agent):
| Variable | Default | Description |
|----------|---------|-------------|
| `BUZZ_ACP_RESPOND_TO` | `owner-only` | `owner-only`, `allowlist`, `anyone`, or `nobody` |
| `BUZZ_ACP_RESPOND_TO_ALLOWLIST` | — | Comma-separated hex pubkeys (required for `allowlist`; owner always implicitly included) |
Memory:
| Variable | Default | Description |
|----------|---------|-------------|
| `BUZZ_ACP_NO_MEMORY` | unset | NIP-AE core-memory prompt injection is **on by default**; set `true` (or pass `--no-memory`) to opt out |
Legacy fallbacks still accepted: `BUZZ_ACP_PRIVATE_KEY`, `BUZZ_ACP_API_TOKEN`, `BUZZ_ACP_TURN_TIMEOUT` (superseded by `BUZZ_ACP_IDLE_TIMEOUT`).
See the [agents guide](../guides/agents.md) for the harness in context and [`crates/buzz-acp/README.md`](../../crates/buzz-acp/README.md) for the complete flag list (owner control commands, subscription rules).
## Desktop app
The desktop app is configured through its own settings UI, not env vars — see [`desktop/README.md`](../../desktop/README.md).
## Troubleshooting quick hits
| Symptom | Fix |
|---------|-----|
| `auth_error: BUZZ_PRIVATE_KEY is required` | Export it into the CLI's shell, or pass `--private-key` |
| `auth_error: BUZZ_AUTH_TAG verification failed` on local relay | `unset BUZZ_AUTH_TAG` — stale attestation from a parent shell |
| `auth-required: verification failed` on a closed relay | Set `BUZZ_AUTH_TAG` to the owner-issued JSON, or relax `BUZZ_REQUIRE_RELAY_MEMBERSHIP` |
| ACP agent ignores all events | Default `BUZZ_ACP_RESPOND_TO=owner-only` with no owner configured — set `anyone` for testing |
| `Address already in use` on relay start | Another relay holds `:3000`/`:8080`/`:9102`; the panic names the port. `pkill -f buzz-relay` or override `BUZZ_BIND_ADDR`/`BUZZ_HEALTH_PORT`/`BUZZ_METRICS_PORT` |
Fuller table: [`TESTING.md` §Troubleshooting](../../TESTING.md) and the [local relay guide](../getting-started/local-relay.md).
Reference in New Issue View Git Blame Copy Permalink