Skip to content

Instantly share code, notes, and snippets.

@anthonyrussano

anthonyrussano/buzz-local-runbook.md

Created July 24, 2026 07:25
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save anthonyrussano/82c2162257a8eac28af96653787002cf to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save anthonyrussano/82c2162257a8eac28af96653787002cf to your computer and use it in GitHub Desktop.
Download ZIP
Buzz local runbook: install, start/stop, desktop/web/mobile, agents/Codex, keyring fix
Raw
buzz-local-runbook.md

Buzz local runbook (from a full setup session)

Personal notes for running block/buzz on Linux: install, start/stop, desktop vs web vs mobile, hosted community, agents/Codex, and the keyring gotcha we hit.

Machine context from this session

  • OS: Linux (Ubuntu-ish), Docker already installed
  • Repo path used: ~/Workspace/buzz
  • LAN IP at the time: 10.32.25.37 (DHCP can change this)
  • Hosted community used on phone: russano.communities.buzz.xyz

What Buzz is (architecture in one minute)

Buzz is not “one Docker web app.”

Layer What it is How it runs
Docker Postgres, Redis, MinIO (+ optional Adminer/Keycloak/Prometheus) docker compose via just setup / bootstrap
buzz-relay The real server (WebSocket + REST) Host process: just relay or as part of just dev
Desktop app Full client (channels, agents UI, etc.) Tauri + React just dev or just desktop-standalone
Web (web/) Repo/forge browser only, not full chat just web or just relay-web
Mobile Full-ish client against a relay URL Install app; point at relay
Agents Local processes (buzz-acp + Codex/Claude/Goose) Started by desktop, not by mobile/web

Identity is Nostr keypairs, not classic email/password web accounts.

Prerequisites

  • Docker (daemon running)
  • Git
  • A graphical session (for desktop app)
  • Optional for phone: same LAN as the host, or a hosted community URL

Hermit (you do not need a separate global install)

Hermit is Cash App’s project-local toolchain manager. The Buzz repo vendors it under ./bin/.

Sourcing the env downloads pinned tools on first use (Rust, Node, pnpm, just, etc.):

cd ~/Workspace/buzz
source ./bin/activate-hermit

Optional global install (not required for this repo):

curl -fsSL https://github.com/cashapp/hermit/releases/download/stable/install.sh | /bin/bash
# installs to ~/bin — add to PATH if needed

Always source ./bin/activate-hermit in a shell before using just / cargo / pnpm from the repo.

Linux desktop (Tauri) system packages

First desktop build failed without GTK/WebKit dev packages. On Ubuntu-like systems:

sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \
  build-essential curl wget file patchelf libssl-dev libxdo-dev \
  libgtk-3-dev libwebkit2gtk-4.1-dev librsvg2-dev \
  libayatana-appindicator3-dev

Notes:

  • Prefer libayatana-appindicator3-dev, not the conflicting older libappindicator3-dev.
  • Runtime libs alone are not enough; you need the -dev packages for the first compile.

One-time setup

mkdir -p ~/Workspace
cd ~/Workspace
git clone https://github.com/block/buzz.git
cd buzz

source ./bin/activate-hermit

# Copies .env.example → .env if needed, pulls Hermit tools,
# starts Docker services, runs migrations, installs JS deps + git hooks
just setup

# Build the Rust workspace (first time can take a few minutes)
just build

After just setup, typical local services:

Service URL / connection
Postgres postgres://buzz:buzz_dev@localhost:5432/buzz
Redis redis://localhost:6379
MinIO localhost:9000–9001
Adminer (DB UI) http://localhost:8082
Keycloak (optional OAuth) http://localhost:8180 (may flap in dev)
Prometheus http://localhost:9090

Check Docker:

docker compose ps

Daily: how to start things

A) Full local stack + desktop window (good for first try)

cd ~/Workspace/buzz
source ./bin/activate-hermit
just dev

What this does:

  1. Ensures Docker services + migrations
  2. Starts buzz-relay on 0.0.0.0:3000 (health on 8080)
  3. Starts the desktop Tauri app
  4. On exit: kills relay + cleans up instance agents

Relay: ws://localhost:3000
Health: http://127.0.0.1:8080/_readiness → {"status":"ready"}

Closing the desktop from just dev takes the local community offline (relay + agents stop). Data is not deleted (Postgres/MinIO volumes remain).

B) Relay only — no desktop window (community online for phone / other clients)

cd ~/Workspace/buzz
source ./bin/activate-hermit
just relay

Leave this terminal running. Desktop is not started. Agents are not running unless something else starts them.

C) Desktop only — connect to a hosted community (no local relay)

For communities like russano.communities.buzz.xyz:

cd ~/Workspace/buzz
source ./bin/activate-hermit
just desktop-standalone

Then in the app, join/connect to your hosted community URL.

⚠️ Keyring gotcha (desktop-standalone)

just desktop-standalone sets:

BUZZ_DEV_KEYRING_SERVICE=buzz-desktop-dev.main

But the first successful just dev session typically stores agent private keys under:

buzz-desktop-dev

If agents fail with:

agent … has no private key available — the OS keyring may be unreachable

the keyring is often fine; the app is looking in the wrong service name. Logs may also say:

buzz-desktop: agent … has no key in JSON or keyring

Fix used in this session: restart desktop without the .main scoped service so it uses buzz-desktop-dev (where keys already live):

cd ~/Workspace/buzz
source ./bin/activate-hermit
cd desktop
source ../scripts/instance-env.sh
export BUZZ_DEV_KEYRING_SERVICE=buzz-desktop-dev   # note: no ".main"
pnpm exec tauri dev --config "$BUZZ_TAURI_CONFIG"

(Or use just dev if you want local relay + default keyring service.)

Linux keyring bits:

  • GNOME Keyring / org.freedesktop.secrets must be available in your graphical session
  • Agent nsecs live in the OS keyring blob, not in managed-agents.json
  • Helper package (optional): sudo apt-get install -y libsecret-tools
  • Inspect (careful — can print secrets):
    secret-tool search --all service buzz-desktop-dev

D) Web UI (repos only — not full Buzz chat)

# Terminal 1: relay
just relay

# Terminal 2: web frontend
just web

In this checkout, Vite chose something like http://localhost:50247/ (port is derived per worktree; read the just web output).

What the web UI is:

  • Community git/repo browser + invite routes
  • Empty state: “This community is empty / repositories pushed…”
  • “Open in Buzz” is a desktop deep link (buzz://connect?…), not a full web login

What it is not:

  • Not channels/DMs/agents as a multi-user browser product
  • Not “expose one URL and everyone logs in like Slack web”

Optional single-origin serve:

just relay-web   # builds web/ and serves from the relay (port 3000)

Stop / offline behavior

Action Relay Agents Docker data
Close desktop from just dev Stops Stops Kept
Stop just relay terminal Stops N/A (weren’t started) Kept
Close desktop only, just relay still running Stays up Usually stop (desktop-owned) Kept
docker compose down (relay may fail next) — Volumes kept unless -v
just reset / wipe scripts — — Destructive — know before using

Useful:

# Stop compose services (keep volumes)
docker compose down

# Status
docker compose ps
curl -sf http://127.0.0.1:8080/_readiness; echo

Bring community back later:

source ./bin/activate-hermit
just relay     # or just dev

Phone / LAN access

Hosted community (what worked for full mobile UX)

Phone on russano.communities.buzz.xyz talks to Block’s hosted relay, not your home PC.

  • Mobile works as a client while that community exists online.
  • Agents still run on a PC (desktop + buzz-acp + Codex/etc.).
  • If agents show offline on mobile: open Buzz desktop on a computer, joined to the same community, leave it running.

Local just relay does not power *.communities.buzz.xyz.

Self-hosted LAN relay (phone → your PC)

  1. Start relay: just relay (binds 0.0.0.0:3000).
  2. Find LAN IP, e.g. hostname -I → 10.32.25.37.
  3. Seed community host rows for that IP (Buzz fails closed on unknown hosts).

Example (same Docker DB as local dev):

docker exec -e PGPASSWORD=buzz_dev buzz-postgres \
  psql -U buzz -d buzz -c "
INSERT INTO communities (host)
VALUES
  ('10.32.25.37'),
  ('10.32.25.37:3000')
ON CONFLICT (lower(host)) DO NOTHING;
SELECT id, host FROM communities ORDER BY host;
"
  1. On phone, set relay to:
ws://10.32.25.37:3000

Important host-binding note:
Each distinct host string (localhost:3000 vs 10.32.25.37:3000) is its own community id in the communities table. Prefer one URL for all clients if you want the same rooms/data. IP changes break seeding until you add the new host.

Firewall: ufw was inactive in this session; if you enable a firewall, allow TCP 3000 on LAN.

Agents + Codex billing

How agents run

Buzz desktop
  → buzz-acp
    → codex-acp (often under ~/.local/share/Buzz/node-tools/…)
      → codex app-server

Preferred runtime in this session’s config: "codex"
(~/.local/share/xyz.block.buzz.app.dev/agents/global-agent-config.json)

Agents open files under ~/.codex/ (shared with normal Codex CLI). Nest dir ~/.buzz-dev is workspace; it does not replace ~/.codex auth.

Plus weekly limits vs API credits

On this machine, ~/.codex/auth.json had:

  • ChatGPT OAuth tokens present
  • OPENAI_API_KEY empty

Buzz-spawned Codex had no OPENAI_API_KEY in process env and used home ~/.codex state.

Result: usage hits ChatGPT Plus / weekly Codex limits, not Platform API prepaid credits.

Buzz docs for codex-acp recommend an API key for the pure API path; subscription auth is what was active here.

To force API credits later: set a real OPENAI_API_KEY and restart agents/desktop. Prefer one clear auth path.

Common commands cheat sheet

cd ~/Workspace/buzz
source ./bin/activate-hermit

just setup          # first-time / repair Docker + deps
just build          # Rust workspace
just dev            # local relay + desktop (tied lifecycle)
just relay          # relay only
just desktop-standalone   # desktop only (watch keyring service!)
just web            # repo web UI against local relay
just relay-web      # relay serves built web UI
just check          # fmt + clippy-ish checks
just reset          # ⚠️ wipe local data — read what it does first

docker compose ps
docker compose logs -f
docker compose down

curl -sf http://127.0.0.1:8080/_readiness; echo

Split-terminal local workflow:

# T1
just relay

# T2
just desktop-dev   # Vite only, or full desktop via other recipes
# and/or
just web

Paths worth knowing (dev desktop)

Path Purpose
~/Workspace/buzz Source checkout
~/.local/share/xyz.block.buzz.app.dev/ Dev app data
~/.local/share/xyz.block.buzz.app.dev/agents/managed-agents.json Agent records (no nsecs in JSON when keyring works)
~/.local/share/xyz.block.buzz.app.dev/agents/logs/ Per-agent logs
~/.local/share/Buzz/node-tools/ Managed codex-acp / node tools
~/.buzz-dev/ Agent nest / workdir
~/.codex/ Codex auth, config, sessions
.env Local relay config (from .env.example)

Troubleshooting

Desktop won’t compile (gdk-3.0 / webkit pkg-config)

Install Tauri Linux deps (see above). Confirm:

pkg-config --modversion gdk-3.0 webkit2gtk-4.1 gtk+-3.0

just dev says port already in use

Something still holds 3000/8080/9102 (often stale buzz-relay). Find and stop it, then retry:

ss -ltnp | rg ':3000|:8080|:9102'
# kill the buzz-relay PID if safe

Web UI says community empty

Expected with no repos; web is forge-only. Use desktop/mobile for chat.

Agents offline on phone

Desktop (or standalone buzz-acp) must be running against the same relay URL as the phone. Mobile does not host agents.

Honey / agent: “no private key” / keyring unreachable

  1. Confirm graphical session + GNOME Keyring / secrets service.
  2. Check you’re not on buzz-desktop-dev.main while secrets are under buzz-desktop-dev (see keyring gotcha).
  3. Relaunch desktop with matching keyring service.
  4. Only as last resort: re-create agents from desktop (new keys) if secrets are truly gone.

Keycloak container restarting

Optional for basic local chat; can ignore for simple relay+desktop testing.

Mental model: “I closed the app — is my community gone?”

  • Live server / agents: offline if they were only kept alive by that just dev session.
  • History / DB / media: still on disk in Docker volumes until you wipe them.
  • Hosted community (*.communities.buzz.xyz): still on Block’s infra; only your agents go offline when your PC stops running them.

Session timeline (what we actually did)

  1. Cloned block/buzz into ~/Workspace/buzz
  2. Activated Hermit (source ./bin/activate-hermit) — no separate Hermit install required
  3. just setup — Docker images, migrations, pnpm installs, hooks; created .env
  4. just build — Rust workspace
  5. just dev — first desktop launch; installed Tauri system deps after GDK build failure; desktop came up
  6. Clarified Docker vs relay vs desktop vs web
  7. just web — browser repo UI at ~:50247; not full chat
  8. Confirmed Codex via Buzz uses Plus weekly limits (ChatGPT auth in ~/.codex)
  9. Explained close-app offline behavior for just dev
  10. just relay only — for headless community; seeded LAN hosts for phone self-host experiments
  11. Phone on hosted russano.communities.buzz.xyz — agents offline without desktop
  12. Started desktop; hit keyring service mismatch (buzz-desktop-dev.main vs buzz-desktop-dev); fixed by launching with BUZZ_DEV_KEYRING_SERVICE=buzz-desktop-dev

Security notes (local dev defaults)

Dev mode is intentionally loose:

  • BUZZ_REQUIRE_AUTH_TOKEN=false warnings
  • Hardcoded dev relay keypair warnings in logs
  • Fine for trusted home LAN experiments; do not expose raw dev relay to the public internet without hardening (auth, TLS, real keys, firewall).

Never commit or paste nsec1… agent/human private keys or keyring secret blobs.

Quick “I just want agents online for my phone on hosted Buzz”

cd ~/Workspace/buzz
source ./bin/activate-hermit

# Prefer the keyring that already has your agent keys:
cd desktop
source ../scripts/instance-env.sh
export BUZZ_DEV_KEYRING_SERVICE=buzz-desktop-dev
pnpm exec tauri dev --config "$BUZZ_TAURI_CONFIG"

In the desktop app:

  1. Open community russano.communities.buzz.xyz (or your community)
  2. Start / enable agents (Welcome team, Honey, etc.)
  3. Leave the desktop machine awake and the app running
  4. Use mobile; agents should show online while that PC process stays up

Generated as a personal gist from a local setup session. Upstream docs: README, ARCHITECTURE.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment