buzz: full architecture documentation
This commit is contained in:
zai-agent
parent
05d0a5b1ab
commit
9a2a7189a6
1 changed files with 118 additions and 0 deletions
118
buzz/ARCHITECTURE.md
Normal file
118
buzz/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
# 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:
|
||||
|
||||
1. **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.
|
||||
2. **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.
|
||||
3. **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
|
||||
Loading…
Reference in a new issue