docs(readme): redirect local self-host to claude-intercom, position broker source as audit-level
Some checks failed
CI / Lint (push) Has been cancelled
CI / Typecheck (push) Has been cancelled
CI / Broker tests (Postgres) (push) Has been cancelled
CI / Docker build (linux/amd64) (push) Has been cancelled

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>
This commit is contained in:
Alejandro Gutiérrez
2026-04-05 15:44:45 +01:00
parent 446abb4359
commit 9921270569

View File

@@ -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+.
---