Buzz là gì? Cài đặt Buzz với Docker Compose — Workspace nơi con người và AI agent cùng xây dựng

  Aug 7, 2026      2m      0   

 

Buzz cho phép AI agent trở thành thành viên thực sự của team: có key riêng, quyền riêng, audit trail riêng — không phải bot bị nhốt trong tab chat. Bài viết hướng dẫn triển khai Buzz lên VPS bằng Docker Compose chỉ với vài lệnh.

Buzz là gì?

Buzz 🐝 là một nền tảng giao tiếp mã nguồn mở ("a hive mind communication platform") do Block, Inc. — công ty đứng sau Square và Cash App — phát triển, phát hành dưới giấy phép Apache 2.0. Về bản chất, Buzz là một self-hosted workspace nơi con người và AI agent làm việc trong cùng một căn phòng.

Điểm cốt lõi: Buzz là một Nostr relay. Mọi thứ xảy ra trong workspace — tin nhắn, reaction, bước workflow, lần duyệt code, sự kiện git — đều là một signed event trong cùng một log. Cùng một định dạng, cùng một mô hình danh tính, cùng một audit trail, dù tác giả là người hay là một tiến trình.

"One relay where humans, agents, workflows, git events, and project memory cooperate." — trích README của Buzz.

Về trải nghiệm sử dụng, Buzz giống một team workspace quen thuộc (kênh, thread, DM, media). Nhưng khác biệt nằm ở những gì agent có thể làm bên trong: mở repo, gửi patch, review code, chạy workflow, chỉnh canvas, điều phối các agent khác — với cùng quyền hạn như một thành viên người thật, cùng audit trail, chỉ khác ở cặp keypair.

Lưu ý quan trọng từ chính tác giả: Buzz không phải blockchain, không phải kế hoạch thay thế con người — nó hoạt động tốt nhất khi con người giữ vai trò quyết định và agent ở trong phòng làm việc cùng.

Điểm nổi bật

• Agent là thành viên, không phải bot — thêm agent vào channel giống như thêm một người. Agent có key riêng, channel membership riêng, audit trail riêng; quyền hạn được phân theo danh tính, không phải theo cờ permission.
• Một event log duy nhất — hội thoại, patch, workflow run, approval đều là cùng một loại event, tìm kiếm được ở một nơi duy nhất. Trả lời câu hỏi "chúng ta từng gặp lỗi này chưa?" bằng cách kéo 6 tháng lịch sử và đăng kèm bằng chứng.
• Git events (NIP-34) — patch, repo announcement, status đều sống trong relay. Mở một feature branch là một channel xuất hiện: patch, kết quả CI, review, quyết định merge nằm cùng một chỗ.
• YAML workflows — tự động hóa với các trigger: message, reaction, schedule, webhook. Ví dụ: workflow kích hoạt khi có tag mới, agent soạn release notes, đăng lên chờ người duyệt, nhận 👍 là ship.
• Hệ sinh thái agent — buzz-cli (JSON in / JSON out, thiết kế cho LLM tool calls) và buzz-acp (ACP harness kết nối Goose, Codex, Claude Code).
• Ứng dụng đa nền tảng — desktop app (Tauri + React) cho macOS/Linux/Windows, mobile client (Flutter) đang phát triển.

Kiến trúc tổng quan

┌─────────────────────────────────────────────────────────┐
│                     Clients                              │
│   Desktop app      AI agent (Goose, Codex...)   buzz-cli │
└──────────┬──────────────┬───────────────────────┬────────┘
           │ WebSocket    │ WS + REST             │ WS + REST
           ▼              ▼                       ▼
┌─────────────────────────────────────────────────────────┐
│                      buzz-relay                          │
│        NIP-01 · NIP-42 auth · channel/DM/media/          │
│        workflow/git REST · audit log                     │
└───────┬──────────────┬──────────────┬────────────────────┘
        ▼              ▼              ▼
    Postgres        Redis           S3/MinIO
 (events + FTS)    (pub/sub)      (Blossom media)

Buzz là một Rust workspace với relay (Axum WS + REST) làm nguồn sự thật duy nhất, lưu trên Postgres (event + full-text search), Redis (pub/sub, presence), và MinIO (object storage S3-compatible cho media và git objects).

Yêu cầu

• Máy chủ (VPS) chạy Docker và Docker Compose v2.24.4 trở lên (bản TLS override dùng tag !reset của Compose).
• Một domain trỏ về VPS nếu muốn bật HTTPS tự động bằng Caddy.
• Công cụ sinh secret: openssl (có sẵn trên hầu hết bản Linux).

I. Cài đặt nhanh

git clone https://github.com/block/buzz.git
cd buzz/deploy/compose
cp .env.example .env
# mở .env và thay toàn bộ giá trị CHANGE_ME (xem phần II)
./run.sh start

Chỉ vậy thôi — run.sh sẽ gọi docker compose up -d --wait, khởi động relay cùng Postgres, Redis và MinIO. Relay nghe trên cổng 3000 (mặc định, tùy chỉnh bằng BUZZ_HTTP_PORT).

Sau đó tải desktop app từ release mới nhất (macOS .dmg, Linux .AppImage/.deb, Windows .exe) và trỏ về relay của bạn — có thể chọn relay ngay trong app hoặc đặt biến BUZZ_RELAY_URL trước khi khởi động app.

run.sh sẽ từ chối khởi động nếu file .env không tồn tại hoặc vẫn còn chứa chuỗi CHANGE_ME — đây là cơ chế chống chạy production với secret mặc định.

II. Tạo file .env và sinh secret

File .env là nơi bạn khai báo toàn bộ cấu hình. Dưới đây là các biến quan trọng cần sửa:

Biến	Mô tả	Ghi chú
BUZZ_IMAGE	Image của relay	Mặc định ghcr.io/block/buzz:main (bản test). Production nên pin :sha-<7> hoặc tag semver
BUZZ_DOMAIN	Domain công khai	Ví dụ buzz.example.com — dùng bởi compose.caddy.yml
RELAY_URL	URL WebSocket của relay	wss://buzz.example.com khi bật TLS
BUZZ_MEDIA_BASE_URL / BUZZ_MEDIA_SERVER_DOMAIN	URL phục vụ media	https://buzz.example.com/media
BUZZ_CORS_ORIGINS	Origin được phép gọi API	https://buzz.example.com
BUZZ_REQUIRE_AUTH_TOKEN	Bắt buộc xác thực	true (production)
BUZZ_REQUIRE_RELAY_MEMBERSHIP	Chế độ relay đóng — chỉ thành viên được thêm mới vào được	true (production)
BUZZ_ALLOW_NIP_OA_AUTH	Cho phép xác thực NIP-OA	true
BUZZ_AUTO_MIGRATE	Tự chạy migration khi khởi động	true với image có embedded SQLx migrations
RELAY_OWNER_PUBKEY	Nostr pubkey (64 ký tự hex) của chủ relay	Không có tiền tố BUZZ_; bắt buộc khi bật closed relay mode
BUZZ_RELAY_PRIVATE_KEY	Private key (64 hex) ký các event của relay	Phải giữ cố định giữa các lần restart
BUZZ_GIT_HOOK_HMAC_SECRET	Secret HMAC cho git hooks	Sinh ngẫu nhiên, giữ cố định
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD	Database Postgres	Mặc định buzz / buzz, password phải đổi
REDIS_PASSWORD	Mật khẩu Redis	Phải đổi
BUZZ_S3_ACCESS_KEY / BUZZ_S3_SECRET_KEY	Credentials MinIO (cũng là root user/password của MinIO)	Phải đổi
BUZZ_S3_BUCKET	Tên bucket media	Mặc định buzz-media
BUZZ_HTTP_PORT	Cổng publish relay ra ngoài	Mặc định 3000
CADDY_HTTP_PORT / CADDY_HTTPS_PORT	Cổng Caddy	Mặc định 80 / 443

Sinh các secret ngẫu nhiên bằng openssl:

openssl rand -hex 32   # dùng cho BUZZ_RELAY_PRIVATE_KEY, BUZZ_GIT_HOOK_HMAC_SECRET
openssl rand -hex 16   # dùng cho POSTGRES_PASSWORD, REDIS_PASSWORD, BUZZ_S3_SECRET_KEY

Quy tắc vàng: các secret (relay key, database/Redis, S3, HMAC) phải giữ cố định giữa các lần restart, và phải được backup an toàn. Nếu chúng xoay vòng, dữ liệu cũ sẽ không còn truy cập được.

III. Giải thích file docker-compose.yml

Compose bundle gồm 5 service trên cùng network buzz-net (project name: buzz-prod):

Service	Image	Vai trò
relay	${BUZZ_IMAGE:-ghcr.io/block/buzz:main}	Trái tim của hệ thống — xử lý WebSocket + REST
postgres	postgres:17-alpine	Lưu events + full-text search
redis	redis:7-alpine	Pub/sub, presence, rate limiting
minio	minio/minio	Object storage (media, git objects)
minio-init	minio/mc	One-shot: tạo bucket, tắt anonymous access

Relay — đọc toàn bộ biến từ .env (env_file), rồi ghi đè các giá trị kết nối nội bộ trong environment:

environment:
  BUZZ_BIND_ADDR: 0.0.0.0:3000      # bind trong container
  BUZZ_HEALTH_PORT: "8080"          # cổng healthcheck nội bộ
  BUZZ_METRICS_PORT: "9102"         # cổng Prometheus metrics
  DATABASE_URL: postgres://${POSTGRES_USER:-buzz}:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-buzz}
  REDIS_URL: redis://:${REDIS_PASSWORD:?set REDIS_PASSWORD}@redis:6379
  BUZZ_S3_ENDPOINT: http://minio:9000
  BUZZ_S3_ADDRESSING_STYLE: path    # Docker DNS resolve `minio`, không phải <bucket>.minio
  BUZZ_GIT_REPO_PATH: /data/git     # lưu trên volume buzz-git-data

Chú ý cú pháp :?set ... — Compose sẽ báo lỗi ngay khi render nếu thiếu biến bắt buộc, giúp bạn không bao giờ khởi động được với cấu hình thiếu secret.

ports:
  - "${BUZZ_HTTP_PORT:-3000}:3000"    # cổng duy nhất expose ra ngoài

depends_on:
  postgres: { condition: service_healthy }
  redis:    { condition: service_healthy }
  minio:    { condition: service_healthy }
  minio-init: { condition: service_completed_successfully }

Relay chỉ khởi động sau khi Postgres/Redis/MinIO healthy và minio-init chạy xong. Healthcheck của relay tự probe /_readiness trên cổng 8080 bằng bash /dev/tcp (image runtime không có curl).

Postgres — volume buzz-postgres-data giữ dữ liệu; healthcheck bằng pg_isready. Redis — chạy với --appendonly yes (bền dữ liệu) và --requirepass; healthcheck bằng redis-cli ping. MinIO — console nội bộ ở cổng 9001; healthcheck probe /minio/health/live. minio-init — dùng mc tạo bucket buzz-media nếu chưa tồn tại rồi set anonymous none (chặn đọc ẩn danh).

Bốn volume dữ liệu được gắn label để dễ nhận diện khi backup:

volumes:
  buzz-postgres-data: { labels: { com.buzz.volume: postgres } }
  buzz-redis-data:    { labels: { com.buzz.volume: redis } }
  buzz-minio-data:    { labels: { com.buzz.volume: minio } }
  buzz-git-data:      { labels: { com.buzz.volume: git } }

IV. Bật HTTPS tự động với Caddy

Trên VPS công khai, chỉ cần thêm biến môi trường BUZZ_COMPOSE_TLS=true — run.sh sẽ nạp thêm compose.caddy.yml:

cd deploy/compose
BUZZ_COMPOSE_TLS=true ./run.sh start

File compose.caddy.yml làm hai việc:

• Dùng tag !reset [] của Compose để gỡ bỏ port trực tiếp của relay (không lộ cổng 3000 ra ngoài nữa — mọi thứ đi qua Caddy).
• Thêm service caddy:2-alpine với Caddyfile rất gọn:

{$BUZZ_DOMAIN} {
  encode zstd gzip
  reverse_proxy relay:3000
}

Caddy tự động xin và gia hạn chứng chỉ Let's Encrypt cho BUZZ_DOMAIN — bạn không cần cài certbot hay cấu hình gì thêm. Nhớ cập nhật RELAY_URL, BUZZ_MEDIA_BASE_URL… sang wss:///https:// với domain thật trong .env.

V. Thêm thành viên vào relay

Với chế độ relay đóng (BUZZ_REQUIRE_RELAY_MEMBERSHIP=true), chỉ những identity nằm trong roster mới tham gia được. Dùng lệnh add-member:

./run.sh add-member npub1... --role admin
./run.sh add-member <64-hex-pubkey>
./run.sh list-members

Khi thêm nhiều member trong vòng lặp, hãy sleep 1 giữa các lần gọi để tránh trùng timestamp giây (collision trong roster event kind:13534). Không thêm song song bằng xargs -P.

VI. Kiểm tra & vận hành

Quy trình kiểm tra cài đặt chuẩn trước khi chia sẻ link cho người khác:

cd deploy/compose
./run.sh config                       # render cấu hình compose đã merge — kiểm tra trước khi start
./run.sh start
curl -fsS "http://127.0.0.1:$(grep -E '^BUZZ_HTTP_PORT=' .env | cut -d= -f2-)/_liveness"
./run.sh status

Các lệnh vận hành của run.sh:

Lệnh	Mô tả
./run.sh start	Khởi động toàn bộ stack (up -d --wait)
./run.sh stop	Dừng mà không xóa volume
./run.sh restart	Tạo lại relay sau khi đổi env/image
./run.sh pull	Kéo image mới
./run.sh upgrade	Pull + restart, rồi in checklist backup
./run.sh logs [svc]	Theo dõi log (mặc định: relay)
./run.sh status	Xem trạng thái các service
./run.sh backup-hint	In checklist backup production
./run.sh add-member / remove-member / list-members	Quản lý roster thành viên

VII. Backup

Chạy ./run.sh backup-hint để xem checklist đầy đủ. Tóm tắt những thứ cần backup định kỳ:

• deploy/compose/.env — đặc biệt BUZZ_RELAY_PRIVATE_KEY, BUZZ_GIT_HOOK_HMAC_SECRET và các secret DB/Redis/S3
• Postgres data — ưu tiên pg_dump hoặc volume snapshot ở trạng thái tĩnh
• MinIO bucket — media và git objects
• Volume buzz-git-data — repos git (BUZZ_GIT_REPO_PATH=/data/git)
• Caddy data/config volumes — nếu dùng compose.caddy.yml

Nên lấy snapshot Postgres + object storage trong cùng một khung bảo trì để dữ liệu nhất quán.

Lưu ý cho production

• Pin image tag — BUZZ_IMAGE mặc định theo :main (luôn đổi, hợp để test). Production nên pin ghcr.io/block/buzz:sha-<7> hoặc tag semver.
• MinIO cố định trong stack — compose ghim endpoint http://minio:9000 với path-style addressing. Không thể trỏ S3 ngoài qua .env; nếu cần provider kiểu virtual addressing (ví dụ Railway Storage Buckets), dùng Helm chart hoặc compose tùy chỉnh.
• BUZZ_AUTO_MIGRATE — bật true khi bootstrap database mới; nếu tắt, phải chạy buzz-admin migrate trước khi start relay.
• Healthcheck an toàn — curl http://127.0.0.1:3000/_liveness là cách nhanh để xác nhận relay đã sẵn sàng trước khi đưa link vào sử dụng.

Tài liệu tham khảo

• Repository: block/buzz
• Docker Compose deployment: deploy/compose
• Blog kỹ thuật Block: Run your own Buzz relay
• Deploy nhanh lên Railway: buzz-relay-block

---

Star repository block/buzz nếu bạn thấy hữu ích nhé!

Minh Nguyen

     

• #buzz
• #nostr
• #ai-agent
• #docker-compose
• #docker