From 9921270569fb39e834e4b790bb548a8e49912104 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alejandro=20Guti=C3=A9rrez?=
 <35082514+alezmad@users.noreply.github.com>
Date: Sun, 5 Apr 2026 15:44:45 +0100
Subject: [PATCH] docs(readme): redirect local self-host to claude-intercom,
 position broker source as audit-level
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Strategic positioning split for v0.1.0:
- Local/single-machine self-host → redirect to claude-intercom (MIT,
  simpler, purpose-built for that case)
- Cross-machine / team → hosted claudemesh.com (E2E encrypted, zero-ops)
- Building the broker from source is an audit/fork path, not the
  primary self-host flow. Enterprise self-host packaging deferred to
  v0.2+.

Previous "Run your own broker" section pushed users toward a docker
pull + self-host flow we're not publishing images for this launch
(ghcr.io/alezmad/claudemesh-broker stays as future enterprise path).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 69 +++++++++++++------------------------------------------
 1 file changed, 16 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index 77de2a4..bb23ce0 100644
--- a/README.md
+++ b/README.md
@@ -111,62 +111,25 @@ walkthrough and troubleshooting.
 
 ---
 
-## Run your own broker
+## Where to run it
 
-You don't need `claudemesh.com`. The broker is a single MIT-licensed binary
-you can host anywhere with Docker + Postgres. Your keypairs stay on your
-machines either way — the broker is just a router that never sees plaintext.
+**Local, one machine, simpler protocol** → use
+[**claude-intercom**](https://github.com/alezmad/claude-intercom) (MIT).
+Same idea, same author, purpose-built for a single laptop. If all your
+Claudes live on one box, start there.
 
-### Prerequisites
+**Cross-machine, cross-team, cross-device** → use the hosted broker at
+**[claudemesh.com](https://claudemesh.com)**. Zero ops. E2E encrypted —
+the broker only routes ciphertext, never sees your content, can't read
+your keys. Sign in, create a mesh, invite peers.
 
-- Docker (or native Bun if you want to run from source)
-- A reachable Postgres 15+ database
-
-### Start the broker (60 seconds)
-
-```sh
-# Pull + run. The image is multi-arch (arm64 + amd64) so Apple Silicon
-# and Linux VPS both get native binaries.
-docker run -d --name claudemesh-broker \
-  -p 7900:7900 \
-  -e DATABASE_URL="postgres://user:pass@your-db:5432/claudemesh" \
-  ghcr.io/alezmad/claudemesh-broker:latest
-
-# verify
-curl -s http://localhost:7900/health
-# → {"status":"ok","db":"up","version":"0.1.0","gitSha":"...","uptime":3}
-```
-
-Point your CLI (or your teammates' CLIs) at it:
-
-```sh
-export CLAUDEMESH_BROKER_URL="ws://localhost:7900/ws"
-# or TLS-fronted via Traefik/Caddy/Cloudflare Tunnel:
-export CLAUDEMESH_BROKER_URL="wss://broker.yourteam.local/ws"
-```
-
-### Or build from source
-
-```sh
-git clone https://github.com/claudemesh/claudemesh
-cd claudemesh
-scripts/build-multiarch.sh ghcr.io/alezmad 0.1.0
-```
-
-### Environment reference
-
-| Variable                    | Default | Purpose                                      |
-| --------------------------- | ------- | -------------------------------------------- |
-| `DATABASE_URL`              | —       | **Required** — `postgres://…` connection URL |
-| `BROKER_PORT`               | `7900`  | HTTP + WebSocket multiplexed on one port     |
-| `MAX_CONNECTIONS_PER_MESH`  | `100`   | WS capacity per mesh (rejects with code 1008)|
-| `MAX_MESSAGE_BYTES`         | `65536` | Max WS payload / hook POST body size         |
-| `HOOK_RATE_LIMIT_PER_MIN`   | `30`    | Per-(pid,cwd) token bucket on `/hook/*`      |
-| `STATUS_TTL_SECONDS`        | `60`    | Stuck-peer idle-flip window                  |
-
-Full runtime contract: **[`apps/broker/DEPLOY_SPEC.md`](./apps/broker/DEPLOY_SPEC.md)**
-(routes, healthcheck, metrics, signals). For Coolify/Traefik/CI,
-see **[`DEPLOY.md`](./DEPLOY.md)**.
+**Want to audit or fork the broker?** Source is MIT in
+[`apps/broker/`](./apps/broker/) — read the [runtime
+contract](./apps/broker/DEPLOY_SPEC.md), read the [protocol
+spec](./docs/protocol.md), build it yourself. Building from source is
+a path for auditors, researchers, and forkers — not the primary
+self-host flow. Enterprise self-hosted broker packaging is on the
+roadmap for v0.2+.
 
 ---