docs: soften claudemesh self-host path, redirect local users to claude-intercom
This commit is contained in:
Alejandro Gutiérrez
32
docs/FAQ.md
32
docs/FAQ.md
@@ -53,20 +53,30 @@ routing metadata. Self-hosting narrows that audience to you.
|
||||
|
||||
## Can I use this without the hosted broker?
|
||||
|
||||
Yes. The broker is a single Bun process + Postgres 16. See
|
||||
[`docs/SELF-HOST.md`](./SELF-HOST.md) for the compose file.
|
||||
**Pick the tool that matches your scope:**
|
||||
|
||||
**Trade-offs:**
|
||||
- **Local, single machine** (your own Claude Code sessions on one
|
||||
laptop): use **[claude-intercom](https://github.com/alezmad/claude-intercom)**.
|
||||
MIT, Unix-socket-based, zero infra. Simpler than claudemesh for
|
||||
the local case.
|
||||
- **Team / cross-machine**: use **hosted claudemesh.com**. Because
|
||||
the broker only ever sees ciphertext, you don't need to own it
|
||||
to own your data — the E2E guarantee (see above) is what earns
|
||||
the trade.
|
||||
- **Audit, fork, enterprise inquiry**: the broker source in
|
||||
[`apps/broker/`](../apps/broker/) is MIT. Read it, run it
|
||||
yourself, or point your CLI at your own instance via
|
||||
`CLAUDEMESH_BROKER_URL`. See [`docs/SELF-HOST.md`](./SELF-HOST.md)
|
||||
for the raw Docker Compose path.
|
||||
|
||||
- **Self-hosted**: you own the metadata surface, you set the TLS
|
||||
boundary, you handle uptime + backups. No federation yet, so
|
||||
your peers can't talk to peers on other brokers.
|
||||
- **Hosted (claudemesh.com)**: zero ops, TLS handled, we run the
|
||||
Postgres, metadata passes through our OVH node. You trade a
|
||||
narrow metadata surface for not having to babysit infra.
|
||||
A packaged enterprise self-host (turnkey, federated, supported)
|
||||
is a **v0.2 paid-tier feature**. What ships today for self-host
|
||||
is the underlying primitives — adequate for auditors and tinkerers,
|
||||
not yet a product.
|
||||
|
||||
The crypto guarantee is identical either way. The difference is
|
||||
who holds the routing metadata.
|
||||
The crypto guarantee is identical across all three paths: only
|
||||
peer endpoints can decrypt. What changes is who holds the routing
|
||||
metadata.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,16 +1,27 @@
|
||||
# Self-hosting the broker
|
||||
# Self-hosting the claudemesh broker
|
||||
|
||||
Run your own `claudemesh` broker when you need **data residency**
|
||||
(payloads stay in your infra), **enterprise isolation** (your own
|
||||
TLS cert, your own auth boundary), or you just want to **tinker**
|
||||
with the protocol. The broker is stateless-ish — presence +
|
||||
offline-queue metadata lives in Postgres — so most ops practices
|
||||
you already have will work.
|
||||
**Most people don't need this page.** Here's the short version:
|
||||
|
||||
> Peers connect with their ed25519 keypair; the broker only routes
|
||||
> ciphertext. Self-hosting doesn't give you access to anyone's
|
||||
> message contents — it just moves the metadata surface to your
|
||||
> side.
|
||||
- **Local peer mesh** (just your own laptop's Claude Code sessions
|
||||
talking to each other): use **[claude-intercom](https://github.com/alezmad/claude-intercom)**
|
||||
— single-machine, Unix sockets, MIT, zero infra.
|
||||
- **Team / cross-machine mesh** (your agents reaching each other
|
||||
across laptops, repos, devices): use **hosted claudemesh**
|
||||
([claudemesh.com](https://claudemesh.com)) — E2E encrypted, so
|
||||
using our broker doesn't cost you data control. Plaintext never
|
||||
leaves the peer.
|
||||
- **Audit / fork / enterprise self-host**: the broker source in
|
||||
[`apps/broker/`](../apps/broker/) is MIT. Read it, fork it, run
|
||||
your own. Instructions below.
|
||||
|
||||
> **Why self-hosting is a narrow path**: the broker only routes
|
||||
> ciphertext. It never sees plaintext, file contents, or prompts.
|
||||
> Self-hosting narrows the metadata surface (who ↔ whom, when,
|
||||
> size) to your infra — it doesn't change the cryptographic
|
||||
> guarantee. For most teams, the hosted broker's zero-ops trade
|
||||
> is the right one. A first-class packaged self-host / enterprise
|
||||
> deploy is a **v0.2 paid-tier feature**; what's here is the bare
|
||||
> primitives for people who want them today.
|
||||
|
||||
---
|
||||
|
||||
@@ -85,23 +96,28 @@ for production deploy notes.
|
||||
|
||||
## Known gaps in v0.1.0 self-host
|
||||
|
||||
Being upfront so you don't hit them cold:
|
||||
Self-hosting claudemesh in v0.1.0 is a **raw-source path**, not a
|
||||
packaged product. Being upfront so you don't hit these cold:
|
||||
|
||||
- **No first-class binary yet.** You run via Docker or `bun`. Native
|
||||
single-file binaries land in v0.2.
|
||||
- **No first-class binary or distribution yet.** You run via Docker
|
||||
or `bun` from the monorepo. A packaged enterprise deploy is a
|
||||
v0.2 paid-tier deliverable — not on the free self-host track.
|
||||
- **No broker federation.** Self-hosted brokers don't talk to each
|
||||
other — peers on *your* broker can't reach peers on *ours* (yet).
|
||||
Federation is on the v0.3 roadmap.
|
||||
- **TLS is your responsibility.** The broker does plain WS; put it
|
||||
behind a reverse proxy for `wss://`.
|
||||
- **Postgres only.** No SQLite fallback right now (it's workable but
|
||||
not shipped). Presence + offline queue use the same Postgres the
|
||||
web app uses — you can share a DB or run a dedicated one.
|
||||
other. Peers on *your* broker can't reach peers on *ours* (yet).
|
||||
Federation is v0.3 roadmap.
|
||||
- **TLS is your responsibility.** The broker speaks plain WS; put
|
||||
it behind Traefik / Caddy / nginx for `wss://`.
|
||||
- **Postgres only.** No SQLite fallback shipped. Presence + offline
|
||||
queue use the same Postgres the web app uses — you can share a
|
||||
DB or run a dedicated one.
|
||||
- **No built-in backups.** Standard Postgres backup tooling applies.
|
||||
Losing the DB loses offline queue + presence, not cryptographic
|
||||
identity.
|
||||
- **Metrics are minimal.** `/health` and `/metrics` exist; Grafana
|
||||
dashboards don't ship yet.
|
||||
- **Minimal metrics.** `/health` and `/metrics` exist; no Grafana
|
||||
dashboards yet.
|
||||
|
||||
If you want a turnkey self-host experience, you probably want to
|
||||
wait for v0.2 — or use the hosted broker today and revisit later.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -55,9 +55,15 @@ with context — without a human writing it up in Slack first.
|
||||
Each Claude stays inside its own repo. Nothing reads anyone else's
|
||||
files. Information flows at the agent layer; humans stay on the PR.
|
||||
|
||||
It's MIT-licensed, E2E-encrypted with libsodium, and you can
|
||||
self-host the broker. WhatsApp / Telegram / iOS gateways are on
|
||||
the roadmap — protocol is ready, the bots aren't shipped yet.
|
||||
It's MIT-licensed and E2E-encrypted with libsodium. For local
|
||||
single-machine use (just your own Claude sessions on one laptop),
|
||||
there's claude-intercom — the OSS ancestor, Unix sockets, MIT:
|
||||
github.com/alezmad/claude-intercom. claudemesh is the hosted
|
||||
cross-machine version — because the broker only sees ciphertext,
|
||||
you don't need to own it to own your data. Broker source is also
|
||||
MIT for audit + forks; a packaged enterprise self-host is v0.2.
|
||||
WhatsApp / Telegram / iOS gateways are on the roadmap — protocol
|
||||
is ready, the bots aren't shipped yet.
|
||||
|
||||
Repo: https://github.com/claudemesh/claudemesh
|
||||
Protocol: https://claudemesh.com/docs
|
||||
@@ -65,8 +71,10 @@ Protocol: https://claudemesh.com/docs
|
||||
Would love feedback, especially on the trust model.
|
||||
```
|
||||
|
||||
Word count: ~215. First-person, honest, leads with a concrete
|
||||
personal pain. No hype words. Ends with a specific ask.
|
||||
Word count: ~260. First-person, honest, leads with a concrete
|
||||
personal pain. No hype words. Ends with a specific ask. Calls out
|
||||
the local-vs-hosted split with claude-intercom so HN doesn't read
|
||||
the hosted broker as vendor-lock-in.
|
||||
|
||||
---
|
||||
|
||||
@@ -101,10 +109,12 @@ notes file; paste verbatim or adapt.
|
||||
> Two reasons. (1) Most peers aren't addressable — phones roam,
|
||||
> laptops NAT, bots live behind firewalls. A broker is the simplest
|
||||
> rendezvous point. (2) Offline queueing — broker holds ciphertext
|
||||
> until the recipient comes back. You can self-host the broker
|
||||
> (it's in the repo, single Node/Bun process) and point the CLI
|
||||
> at your own via `CLAUDEMESH_BROKER_URL`. We run the hosted one so
|
||||
> teams can start in 60 seconds.
|
||||
> until the recipient comes back. The broker only sees ciphertext,
|
||||
> so trust comes from the crypto, not from owning the server. If
|
||||
> you only need local (same machine), use claude-intercom — same
|
||||
> model, Unix sockets, zero infra. Broker source is MIT and you
|
||||
> can run it yourself via `CLAUDEMESH_BROKER_URL`, but a packaged
|
||||
> enterprise self-host is v0.2.
|
||||
|
||||
### 4. "How is this different from MCP already?"
|
||||
|
||||
@@ -138,10 +148,14 @@ notes file; paste verbatim or adapt.
|
||||
|
||||
**Title**: `Claudemesh: peer-to-peer mesh that lets agents (Claude, Ollama, etc.) reference each other's work`
|
||||
|
||||
**Body**: 2 paragraphs. Lean into: (a) self-hosted broker, (b) it's
|
||||
transport-agnostic — the agent doesn't have to be Claude. Emphasize
|
||||
MIT + libsodium crypto. LocalLLaMA audience cares about escaping
|
||||
hosted services, so lead with the self-host angle.
|
||||
**Body**: 2 paragraphs. Lean into: (a) protocol-open + MIT, (b)
|
||||
it's transport-agnostic — the agent doesn't have to be Claude, any
|
||||
ed25519 client works. Point local-only users at claude-intercom
|
||||
(single machine, Unix sockets, MIT). Point cross-machine users at
|
||||
hosted claudemesh with the E2E framing: the broker only sees
|
||||
ciphertext, so using our infra doesn't cost data control. Note
|
||||
that broker source is MIT for audit/forks, and enterprise packaged
|
||||
self-host is a v0.2 deliverable.
|
||||
|
||||
### r/ClaudeAI (Reddit)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user