You can run Buzz on a single VPS with Docker Compose: copy the example environment file, replace every CHANGE_ME value, and run `./run.sh start` from the `deploy/compose` folder of the block/buzz repository. Setting `BUZZ_COMPOSE_TLS=true` gets a Let's Encrypt certificate through Caddy. The parts that need care are the keys you must never rotate by accident, backups of Postgres and object storage, and how your AI agents get their own identities.
We read the Buzz README, the Compose deploy guide, the buzz-acp harness docs and SECURITY.md on October 29, 2026. Buzz is open source under Apache 2.0, published by Block, and still pre-1.0. Only the main branch is actively supported, so pin a version and check the repo before you upgrade.
What Buzz is, in one paragraph
Buzz is a self-hosted team chat relay built on the Nostr protocol. People and AI agents share channels, threads, direct messages, canvases and files, and every action lands in a hash-chained audit log. The README lists what works today: the relay, channels, threads, DMs, canvases, media, search, the audit log, a desktop app built with Tauri, the buzz-cli and ACP agent harness, YAML workflows, Git events and Git hosting. Mobile apps and workflow approval gates are still being built. If you are comparing it with OpenClaw or Hermes Agent, our OpenClaw vs Hermes Agent vs Buzz comparison covers where each one fits.
What you need before you start
- A Linux VPS with Docker and Docker Compose v2.24.4 or newer. The Compose guide states that minimum.
- A domain name pointed at the server if you want TLS from Let's Encrypt.
- Somewhere to keep secrets that is not the server itself, such as a password manager.
- A backup target for Postgres dumps and object storage.
Buzz does not publish minimum CPU or memory figures. The Compose stack runs the relay plus Postgres, Redis, a MinIO-compatible object store (the Silo fork, pgsty/silo) and a Git volume, so size the server for those five pieces and your expected file uploads. Start small, watch memory for a week, and resize if you need to.
Step 1: get the deploy folder
Clone the repository and move into `deploy/compose`. Do not run from a random branch. Pin the image instead: set `BUZZ_IMAGE` to a specific `ghcr.io/block/buzz:sha-<7 characters>` tag or a release tag, so an upgrade only happens when you choose it.
Step 2: fill in the environment file
Copy `.env.example` to `.env` and replace every CHANGE_ME value. Four groups of values matter most:
- 1The relay private key (`BUZZ_RELAY_PRIVATE_KEY`). This is the relay's identity. Keep it stable. Changing it later breaks trust with every client and agent that knows the relay.
- 2The Git hook secret (`BUZZ_GIT_HOOK_HMAC_SECRET`). Also keep it stable once set.
- 3Database, Redis and object storage passwords. Changing these without updating the running services locks the relay out of its own data.
- 4The owner key (`RELAY_OWNER_PUBKEY`). A 64-character hex public key. Setting it puts the relay in closed mode, where only members you add can connect. For a business, closed mode is the sensible default.
Run `./run.sh config` to print the resolved configuration and check it before the first start.
Step 3: start it, with TLS
`./run.sh start` brings the stack up. With `BUZZ_COMPOSE_TLS=true`, Caddy requests a certificate and terminates HTTPS in front of the relay. SECURITY.md is explicit that TLS has to be terminated either at the relay or at a proxy in front of it, so do not expose a plain HTTP relay to the internet.
Database migrations run when `BUZZ_AUTO_MIGRATE=true` is set, or by hand with `buzz-admin migrate`. On a production server we prefer the manual command, so a schema change happens when someone is watching.
Check health with `./run.sh status` and the liveness endpoint: `curl http://127.0.0.1:$BUZZ_HTTP_PORT/_liveness`. Mobile push notifications are off by default.
Tell us where it should run. We'll reply with the setup plan and the fixed $3,000 price.
Step 4: add people and agents
Each person and each AI agent gets its own Nostr keypair. `buzz-admin generate-key` creates one and prints the secret once; Buzz does not store it, so save it straight into your secrets manager. Then register the public key with `buzz-admin add-member --pubkey <key>`. That command needs the relay key, so run it on the server.
Channel membership is the only access control in Buzz. Decide which channels each agent may join before you add it, and keep agents out of channels where they have no job.
Step 5: connect AI agents with buzz-acp
buzz-acp is the harness that lets coding and assistant agents take part in channels. It speaks the Agent Client Protocol (ACP) over stdio. The docs list three supported agents:
| Agent | How it connects | What it needs |
|---|---|---|
| goose | Native ACP | Its own model settings |
| Codex | Through codex-acp | `OPENAI_API_KEY` |
| Claude | Through claude-agent-acp, set with `BUZZ_ACP_AGENT_COMMAND=claude-agent-acp` | `ANTHROPIC_API_KEY` |
It reads `BUZZ_PRIVATE_KEY` (the agent's own key) and `BUZZ_RELAY_URL`. `BUZZ_ACP_MCP_COMMAND` lets you attach one MCP server for tools. `BUZZ_ACP_AGENTS` sets how many agent processes run, from 1 to 32. The defaults stop an idle agent after 620 seconds and cap one turn at 7,200 seconds. An inbound author gate controls whose messages an agent will answer, which is the setting to check first: an agent that answers anyone in a channel can be steered by anyone in it.
One known gap from the docs: there is no API yet for managing private channel membership, so plan to do that by hand for now.
Step 6: backups and upgrades
`./run.sh backup-hint` prints what to back up. At minimum that is the Postgres database, the object storage bucket, the Git volume and your `.env` file, stored somewhere off the server. Test a restore on a second machine before you rely on it.
For upgrades, read the release notes, back up, change `BUZZ_IMAGE` to the new tag, run migrations, then restart. Because Buzz is pre-1.0, expect breaking changes between versions.
Security notes worth reading twice
- The audit log is tamper-evident, not tamper-resistant. Each entry is chained with SHA-256, so an edit shows up, but someone with server access could still delete the log. Ship copies somewhere else if you need them for compliance.
- Authentication uses NIP-42 for the relay and NIP-98 for the REST API. Keys are kept in the operating system keyring, with a file fallback at 0600 permissions.
- Vulnerability reports get an acknowledgement within 48 hours, according to SECURITY.md.
For the wider list of checks before any self-hosted agent goes live, see our self-hosted AI agent deployment checklist and our post on trust boundaries for self-hosted agents.
Other ways to run it
The repository also ships a Helm chart for Kubernetes and a one-click relay template for Railway. Compose on one VPS is the simplest of the three for a small team. Kubernetes only makes sense if you already run a cluster.
How a small business would use this
A Buzz relay gives a team one place where people and agents work in the same threads, on a server you control. Typical first uses we see a fit for:
- An internal support channel where an agent drafts answers from your docs and a person posts them.
- A build or ops channel where a coding agent reports on Git events and opens fixes for review.
- A shared canvas the agent keeps up to date, such as a weekly status page.
What we would set up around it
When we install Buzz for a client, we run it in closed relay mode, give every agent its own key and the fewest channels it needs, set the inbound author gate to named people, attach only the MCP tools the job needs, and send the audit log and backups off the server. We also write a one-page runbook covering restarts, upgrades and how to remove an agent. Our AI agent governance rules apply the same way they do on any other platform.
When it is not worth self-hosting
If your team is happy in Slack or Teams and the only goal is a chat bot, a hosted tool is less work. Self-hosting means you own patching, backups and uptime. It earns its keep when you need the data on your own server, want agents and people in the same audited threads, or plan to run several agents that need separate identities.
How this fits implementation work
Our Buzz setup package is $3,000 for setup plus $400 a month for maintenance. It installs on infrastructure you own, and model provider accounts stay in your name. The full price list is on our pricing page, and the AI agent cost guide explains model and hosting costs. If you are not sure Buzz is the right platform, our free automation audit will look at your use case and tell you which option fits.
Independence and limitations
OrchestriAI is not affiliated with Block. This guide reflects the Buzz repository as read on October 29, 2026. Buzz is pre-1.0, and file names, environment variables and commands can change between releases, so check the current deploy guide before you run anything in production.
