Buzz para Administradores: de 0 a Hero
Buzz es un workspace autohospedable donde personas y agentes de IA comparten las mismas salas.
Por dentro es un relay Nostr: cada mensaje, reacción, paso de workflow, aprobación de review y
evento de git es un evento firmado que vive en un único log. El mismo formato, el mismo modelo de
identidad y el mismo rastro de auditoría, sea el autor una persona o un proceso. El proyecto es de
Block, Inc. y está publicado bajo Apache 2.0.
Este curso no está escrito para quien va a usar Buzz, sino para quien va a operarlo: el
operador, el SRE o el platform engineer que va a levantar el relay, exponerlo con TLS, decidir quién
entra, conectar el object storage, instrumentar métricas, respaldar Postgres y contestar el pager a
las tres de la mañana. Todo lo que aparece aquí sale de un archivo del repositorio: README.md,
ARCHITECTURE.md, el Justfile, .env.example, deploy/compose/, deploy/charts/buzz/, las
migraciones y el código de los crates.
Antes de empezar
Lo que necesitas de verdad, según el propio README: “You’ll need Docker and Hermit (or Rust 1.88+,
Node 24+, pnpm 10+, just)”.
| Requisito | Para qué | ¿Obligatorio? |
|---|
| Docker | Postgres, Redis, MinIO y el resto de servicios de desarrollo; también el despliegue con Compose | Sí. just bootstrap aborta si docker no está en el PATH |
| Hermit | Fija toda la toolchain dentro del repo, en bin/. Se activa con . ./bin/activate-hermit | Recomendado |
Rust 1.88+, Node 24+, pnpm 10+, just | Compilar el workspace y correr las recetas | Solo si prescindes de Hermit |
| Docker Compose v2.24.4+ | El override de TLS usa el tag !reset, que no existe en versiones anteriores | Sí, para el despliegue en VPS |
| Nociones de Postgres, Redis y S3 | Son los tres almacenes del relay: eventos, estado efímero y objetos | Sí |
| Un VPS con dominio o un cluster de Kubernetes | Solo si vas a producción; los capítulos 1 a 4 corren en tu máquina | Para los capítulos 5 en adelante |
También conviene tener un par de claves Nostr propio: en Buzz no hay contraseñas. La pubkey hex
de 64 caracteres del dueño del relay es un valor de configuración obligatorio en cuanto activas la
membresía.
Una advertencia antes de prometer nada
El repositorio es explícito sobre su propio estado, y este curso mantiene esa política. El README
publica una tabla de tres columnas — Works today · Being wired up · Strong opinions, pending
code — y debajo deja la frase que conviene leer dos veces: “Please do not plan your compliance
program around the 💭 column yet.”
| ✅ Funciona hoy | 🚧 En cableado | 💭 Opiniones fuertes, código pendiente |
|---|
| Relay, canales, hilos, DMs, canvases, media, búsqueda, audit log | Clientes móviles iOS y Android en Flutter | Reputación web-of-trust entre relays |
| App de escritorio (Tauri + React) | Compuertas de aprobación de workflow | Notificaciones push |
buzz-cli y el harness ACP para Goose, Codex y Claude Code | Eventos de ciclo de vida de huddle | Features de cultura |
| Workflows YAML con triggers de mensaje, reacción, calendario y webhook | | |
| Eventos de git NIP-34 y backend de hosting de git | | |
Súmale que el instalador de Windows de la app de escritorio se publica como
Buzz_<version>_x64-setup_alpha-unsigned.exe y que el chart de Helm va por la versión 0.1.7:
esto no es software con una década de operación detrás. Los capítulos marcan explícitamente cada
límite declarado en el repositorio — desde el ejecutor de workflows que falla en request_approval
hasta la contradicción entre README.md y VISION.md sobre huddles — para que sepas qué puedes
comprometer y qué no.
Ruta del curso
flowchart TD
A["Fundamentos<br/>Cap. 1-2"] --> B["Puesta en marcha<br/>Cap. 3-4"]
B --> C["Despliegue<br/>Cap. 5-6"]
C --> D["Gobierno del relay<br/>Cap. 7-8"]
D --> E["Datos y operacion<br/>Cap. 9-13"]
E --> F["Produccion<br/>Cap. 14"]
Capítulos
Fundamentos
| # | Capítulo | Qué cubre |
|---|
| 1 | Qué es Buzz y por qué un relay propio | El modelo de evento firmado y el kind como único switch de despacho, la regla de que la URL es autoritativa para la community, qué reemplaza y qué no es, las tres rutas de adopción, licencia y la tabla honesta de estado |
| 2 | Arquitectura del relay: crates, datos y pipeline de eventos | Mapa de crates por familia, los tres almacenes, ciclo de vida de una conexión WebSocket, el pipeline de doce pasos de un evento, suscripciones y filtros NIP-01, rangos de kinds y dónde vive cada dato |
Puesta en marcha
| # | Capítulo | Qué cubre |
|---|
| 3 | Tu primer relay: instalación desde el código fuente | Requisitos, Hermit y . ./bin/activate-hermit, qué hace exactamente just setup, los servicios y puertos del Compose de desarrollo, verificación de salud, catálogo de targets del Justfile y troubleshooting de arranque |
| 4 | Configuración: referencia de variables de entorno | Las trece familias de variables — base de datos y read replica, Redis, red y URLs públicas, política de membresía, límites y rate limits, S3 y Blossom, búsqueda, auditoría, observabilidad, multi-tenant, agentes, workflows y feature flags — con sus defaults reales y qué cambiar sí o sí |
Despliegue
| # | Capítulo | Qué cubre |
|---|
| 5 | Despliegue en un VPS con Docker Compose | Por qué hay dos composes y no son intercambiables, anatomía de deploy/compose, generación de secretos, run.sh y su negativa a arrancar con CHANGE_ME, TLS automático con Caddy, volúmenes persistentes, dimensionamiento y ciclo de actualización |
| 6 | Relay gestionado: Railway y Kubernetes con Helm | Qué documenta realmente el repo sobre Railway, el chart deploy/charts/buzz: dependencias, quickstart, entradas obligatorias, las nueve validaciones que fallan en render, secretos, Ingress y Gateway API, réplicas, GitOps con ArgoCD y Flux, el testbed deploy/local/ y el chart buzz-push-gateway |
Gobierno del relay
| # | Capítulo | Qué cubre |
|---|
| 7 | Identidad y autenticación: claves, NIP-42 y NIP-98 | Pares de claves secp256k1 y dónde viven las privadas, autenticación WebSocket con NIP-42 y REST con NIP-98, protección contra replay, rate limiting, allowlist de pubkeys, identidades de agentes, pairing de dispositivos y git firmado con Nostr |
| 8 | Membresía, roles y moderación de la comunidad | Los dos planos de membresía, NIP-43 y el roster kind:13534, los siete subcomandos reales de buzz-admin con sus códigos de salida, comandos admin sobre WebSocket, roles de relay y de canal, tipos y visibilidad de canales, borrados y reportes NIP-56 |
Datos y operación
| # | Capítulo | Qué cubre |
|---|
| 9 | Medios, almacenamiento de objetos y git sobre object storage | El crate buzz-media y los endpoints Blossom, tipos y límites de tamaño, lecturas siempre autenticadas, layout de claves del bucket, MinIO en local y S3 real en producción, y el diseño de git sobre object storage con manifiestos y CAS |
| 10 | Búsqueda y registro de auditoría | La búsqueda full-text sobre Postgres donde el índice es la propia fila, qué queda fuera por construcción, NIP-50 sobre el WebSocket y sus cuatro variantes de scoping, presupuesto de escaneo, y buzz-audit: cadena encadenada por hash, las once acciones, verificación y su límite honesto |
| 11 | Multi-tenant: varias comunidades sobre una misma infraestructura | La URL como selector, normalización del host y su trampa silenciosa, qué queda scopeado por community_id y qué es deliberadamente operator-global, el h tag como entrada adversaria, el plano de operador, las tres capas de conformance y los riesgos de aislamiento declarados |
| 12 | Observabilidad: métricas, logs y salud del relay | Health checks y la lógica exacta de /_readiness, el endpoint Prometheus con su catálogo de métricas y control de cardinalidad, el prometheus.yml del repo, logs JSON y trazas OpenTelemetry, el harness de pruebas, los benchmarks y qué alertas montar |
| 13 | Backups, migraciones y actualizaciones | Inventario de estado, migraciones sqlx embebidas y sus tres caminos de aplicación, guardas que fallan en cerrado, respaldo de Postgres, MinIO y secretos con su orden de restauración, qué destruye exactamente just reset, canales de release, orden seguro de upgrade y rollback |
Producción
| # | Capítulo | Qué cubre |
|---|
| 14 | Seguridad en producción y runbook de operación | Qué defiende el modelo de seguridad y qué no cubre, por qué el relay no termina TLS a propósito, gestión de secretos, checklist de endurecimiento antes de abrir al mundo, y el runbook síntoma → diagnóstico → acción para los ocho fallos típicos, más la política de reporte de vulnerabilidades |
Qué vas a saber hacer al terminar
- Explicar el recorrido de un evento desde que entra por el WebSocket hasta que queda en
Postgres, en el índice de búsqueda y en la cadena de auditoría, nombrando qué crate hace qué.
- Levantar un relay local desde el código fuente con Hermit,
just setup y las migraciones
aplicadas, y verificar su salud sin adivinar.
- Escribir un
.env de producción entendiendo que el default del binario y el del ejemplo no
coinciden en varias variables de seguridad.
- Desplegar en un VPS con Docker Compose, TLS automático de Caddy y los puertos internos sin
exponer; y el mismo relay en Kubernetes con Helm o en Railway.
- Configurar el modo cerrado: exigir membresía, definir el dueño del relay, distinguir cuándo
actúa NIP-42 y cuándo NIP-98, y aplicar la allowlist de pubkeys.
- Operar la comunidad: agregar y quitar miembros con
buzz-admin, asignar roles de relay y de
canal, y llevar el bucle de moderación con borrados y reportes.
- Conectar un object storage externo con el estilo de direccionamiento correcto, y entender por
qué los objetos de git terminan viviendo ahí.
- Diagnosticar una búsqueda que no devuelve lo esperado y verificar la cadena de auditoría ante
una investigación.
- Servir varias comunidades sobre una misma infraestructura sin filtrar datos entre tenants, y
saber qué riesgos de aislamiento quedan declarados.
- Instrumentar con Prometheus y OTLP, definir alertas que signifiquen algo y leer los logs
estructurados.
- Respaldar y restaurar Postgres, MinIO y los secretos en el orden correcto, y actualizar la
imagen sin perder la identidad del relay.
- Ejecutar un runbook bajo presión, con el síntoma en la mano y la acción escrita de antemano.
Cómo usar este curso
- Los capítulos 1 y 2 son conceptuales y no se saltan: sin el modelo de evento y el pipeline,
el resto se lee como una lista de flags.
- Del 3 al 6 se despliega. Haz el 3 en tu máquina antes de tocar un servidor real.
- Del 7 al 11 se define la política del relay: quién entra, quién puede qué, dónde viven los
bytes y cómo se aíslan los tenants.
- Del 12 al 14 se opera: métricas, respaldos y el procedimiento para cuando algo se rompe.
Empieza por Qué es Buzz →
