From d0dfce6e33273a2637cfdd734b3d899b88ff6ef8 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:46:11 +0100 Subject: [PATCH] docs: soften claudemesh self-host path, redirect local users to claude-intercom --- docs/FAQ.md | 32 ++++++++++++------- docs/SELF-HOST.md | 62 +++++++++++++++++++++++-------------- marketing/launch/hn-post.md | 40 ++++++++++++++++-------- 3 files changed, 87 insertions(+), 47 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 2749504..7c06ee7 100644 --- a/docs/FAQ.md +++ b/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. --- diff --git a/docs/SELF-HOST.md b/docs/SELF-HOST.md index 0cdcbb9..0b1426b 100644 --- a/docs/SELF-HOST.md +++ b/docs/SELF-HOST.md @@ -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. --- diff --git a/marketing/launch/hn-post.md b/marketing/launch/hn-post.md index 0060871..cf4195f 100644 --- a/marketing/launch/hn-post.md +++ b/marketing/launch/hn-post.md @@ -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)