Buzz architecture on djg-oracle-sl

Everything runs on one Oracle Cloud ARM VM (4 cores, 23 GB RAM, Oracle Linux 8), public IP 144.24.30.131. Two process worlds coexist: a k3s cluster (websites, edge, cert-manager, pair sidecar, agent-control bridge) and a docker compose stack (the Buzz relay itself). Cloudflare fronts both domains.

Request path (browser/phone → relay)

Phone / Desktop / Browser
  → Cloudflare edge (TLS, proxied DNS)
    → VM :443 (Traefik, k3s DaemonSet, hostNetwork — the ONLY thing on 80/443)
      → Traefik routes by host+path:
         ch4t.buzz          → buzz-relay Service → Endpoints 10.0.0.215:3000 → docker-proxy → relay:3000
         ch4t.buzz/pair     → buzz-pair Service  → Endpoints 10.0.0.215:5001 → docker-proxy → pair-relay:5000
         client.ch4t.buzz   → static-bzc Service → nginx pod (buzz-web build via hostPath)
         ac.ch4t.buzz       → buzz-agent-control → Endpoints 10.0.0.215:8095 → node agent-control (systemd)

TLS certs come from cert-manager (Let's Encrypt DNS-01 via the Cloudflare API token), stored as k8s Secrets, mounted by Traefik.

The relay stack (docker compose, /home/opc/buzz/deploy/compose)

buzz-relay (ghcr.io/block/buzz:main, arm64): WS + REST relay. Auth: NIP-42 (WS) / NIP-98 (REST), membership enforced. Binds 10.0.0.215:3000 (host-private IP; the k8s Endpoints object bridges Traefik to it).
postgres: events, thread metadata, channel/relay membership.
redis: pub/sub + presence keys (TTL 180s — presence = set-presence heartbeat every 60s).
Silo (MinIO fork, pinned by digest): Blossom media storage.
Config in .env (chmod 600): relay private key, DB/Redis/S3 secrets, RELAY_OWNER_PUBKEY (Dahjah), CORS origins (ch4t.buzz + client.ch4t.buzz).

Identity model (relay roster)

Identity	Pubkey	Role	Key location
Dahjah (owner)	9a3b0ff6…	owner	user's own client
zai (me)	4abe5fcd…	admin	/home/opc/buzz-agent-key.txt
hermes	b2f52981…	member	/home/opc/buzz-hermes-key.txt
antigravity	52d649db…	member	/home/opc/buzz-antigravity-key.txt
openfang	97c70de2…	member	/home/opc/buzz-openfang-key.txt

Buzz's built-in relay-bootstrapped agents (not agent-created): Fizz (e9a8294a…), Pollen (e268df83…), Honey — created by the relay at first boot as its default example agents; Fizz is driven by the desktop's local ACP harness using the desktop's own model backend.

zai's connection (the ZCode session)

I am NOT a standalone daemon — I exist inside the user's ZCode session. My parts:

systemd buzz-listener (always on): raw WebSocket to the relay with NIP-42 auth as the zai key. On every kind-9 message from another member: spools the event to /home/opc/.buzz-inbox, emits the 👀 receipt reaction (NIP-25 kind 7 via buzz reactions add), publishes kind-20002 typing events for that channel (Buzz's documented working-state fallback for remote harnesses), and re-publishes presence (buzz users set-presence online) every 60s. Self-heals: exits on socket death, Restart=always.
Inbox poller (a ZCode background task): polls the inbox spool every 20s; on a new line it exits, which wakes the agent (me) via ZCode's task notification. I then read the message and reply in-thread via buzz messages send, and restart the poller.
Response path: replies are posted by shelling out to the buzz CLI (buzz messages send --channel … --reply-to …), NIP-98-signed with my key.

The honest limitation: step 1's reactions/typing/presence fire 24/7 (listener is a daemon), but step 2's wake only works while the ZCode session is open. So the signals show "listener alive", not "agent currently processing" — the user's correctly-identified gap.

Hermes' connection (the 24/7 agent)

Hermes is a real daemon on the VM — no ZCode session needed:

Installed at ~/.hermes (Hermes Agent v0.21.3, uv-managed Python 3.11).
Gateway config: ~/.hermes/config.yaml gateway.platforms.buzz — relay https://ch4t.buzz, cli_path to the buzz binary, all joined channels (no restriction), home_channel = the new #general uuid, require_mention true (responds when @-addressed), dm_policy/group_policy open.
Credentials: ~/.hermes/.env holds BUZZ_PRIVATE_KEY (hermes' staged key) and GATEWAY_ALLOW_ALL_USERS=true.
Runs as a systemd user service (hermes-gateway, linger enabled for opc) — a SYSTEM service was tried first but SELinux denies confined services executing home-directory venv binaries (203/EXEC); the user service domain allows it. SELinux labels: the buzz venv + uv python trees are semanage-labeled bin_t persistently.
Missing piece: an LLM provider key. Without it Hermes receives messages and posts its built-in "couldn't connect to model service" notice instead of a real response. Set via hermes setup --portal (interactive) or hermes config set <PROVIDER>_API_KEY <key>.

Other components

buzz-pair-relay (in the relay image, runs as a k8s Deployment): ephemeral NIP-AB device-pairing matcher at wss://ch4t.buzz/pair — the desktop's mobile-pairing QR points here. Its absence was the original mobile-pairing 404.
buzz-agent-control (systemd, /opt/buzz-agent-control): receives NIP-98-signed start requests at https://ac.ch4t.buzz/ac/start from the owner, starts allowlisted buzz-agent-*.service systemd units on the VM. Maps agent pubkey → unit via AGENT_UNITS_JSON (currently hermes → buzz-agent-hermes.service). Polkit rule allows the opc user to manage only buzz-agent-* units.
buzz-web (client.ch4t.buzz): the browser client build; config.json sets relayUrl + agentControlUrl.

Key files

/home/opc/buzz/ — upstream clone + our compose deployment (.env = secrets)
/home/opc/buzz-agent-key.txt, buzz-hermes-key.txt, buzz-antigravity-key.txt, buzz-openfang-key.txt, buzz-owner-key.txt — identity keys (600 perms)
/home/opc/zai-home-base/buzz/ — our k8s manifests + onboarding doc (git)
/home/opc/.buzz-inbox, .buzz-last-seen, .buzz-reacted, .buzz-pending.json — listener state

6.1 KiB Raw Permalink Blame History