buzz/docs/reference/configuration.md

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:

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) 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.

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.

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).

Agent harness (buzz-acp)

Every env var has a matching CLI flag. Core (from 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 for the harness in context and 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.

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 and the local relay guide.