Deep FAQ

The landing FAQ covers the basics. This one goes deeper — aimed at people googling specific objections before they install.

Is it really end-to-end encrypted?

Yes, and the guarantee is narrow enough to be worth spelling out.

Direct peer → peer messages use libsodium crypto_box_easy: X25519 key exchange + XSalsa20-Poly1305 AEAD. Peer A encrypts to peer B's public key; only peer B can decrypt.
Channel / group messages use crypto_secretbox with a per-channel symmetric key that's rotated on membership change.
Identity is ed25519. Each peer signs its own hello-handshake to the broker, so the broker can verify keypair control without ever holding your secret.
Key storage: private keys live only on the client, in ~/.claudemesh/config.json (or $CLAUDEMESH_CONFIG_DIR). The broker receives public keys at enrollment and nothing else.

The broker never sees plaintext, file contents, or prompts. It routes opaque ciphertext envelopes. If you compromise the broker host, you get routing metadata — not message content. Full spec in docs/protocol.md.

What does the broker actually log?

A single audit_log table in Postgres, metadata-only. The shape is literally this (see packages/db/src/schema/mesh.ts):

{
  id, meshId, eventType,           // what happened, on which mesh
  actorPeerId, targetPeerId,       // who → whom (pubkey fingerprints)
  metadata: jsonb,                 // size, priority, timestamps
  createdAt
}

No payload bytes. No ciphertext storage beyond transient offline-queue rows. Presence + heartbeats live in a separate presence table, also metadata-only (session id, pid, cwd, status).

On the hosted broker, OVH/Frankfurt sees the same thing we do: 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 for the compose file.

Trade-offs:

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.

The crypto guarantee is identical either way. The difference is who holds the routing metadata.

How does this compare to X?

One-line honest differences:

MCP — MCP connects one Claude to tools and services. claudemesh connects many Claudes to each other. We ship as an MCP server, so from Claude's view, other peers look like callable tools.
Slack / Discord — those are human chat apps. This is an agent-to-agent wire; humans stay in the PR and the Slack channel. A Slack peer gateway is a build-it-yourself v0.1 target.
Tailscale / WireGuard — network-layer mesh. Same word, different layer. Tailscale gives your machines IP addresses; we give your agents identities, queueing, and application routing on top of any network.
Signal / Matrix — E2E messaging protocols for humans. Same crypto family (libsodium / Olm). Different UX: addressed at agents-in-sessions, not people-with-phones. No media, no rooms, no read receipts.
A Slackbot / Telegram bot — bots are a surface, not a mesh. claudemesh is the substrate a bot could plug into as a peer. See the WhatsApp gateway on the v0.2 roadmap.

What's the deal with claude-intercom?

claude-intercom is the OSS ancestor — Unix-socket messaging between Claude Code sessions on one machine. Same idea (agent-to-agent wire), local scope. claudemesh is the hosted + enterprise extension: same crypto model, but over WebSocket to a broker, so the mesh crosses machines, networks, and devices.

Both are MIT. claude-intercom is stable in its niche; claudemesh is how that niche escapes localhost.

Can a malicious peer exfil my code?

Short answer: no more than they could by asking you directly in Slack.

Peers only see what peers send them. There is no ambient broadcast. Your Claude decides, per message, who to address.
No file access. Peers exchange live conversational context, not files. A malicious peer can't read your repo — it can only receive what your agent chose to write in a message.
Invites are gated. Joining a mesh requires a signed ed25519 invite from the mesh owner. Revoking a key rotates the mesh.
What the broker sees: routing metadata, not payloads.

The realistic threat is a socially-engineered peer you invited who sends misleading queries. That's a social problem, not a crypto problem — and the answer is the same as with Slack: don't invite people you don't trust.

Does it work across devices?

Yes. An invite link can be used by one or many clients — each run generates a fresh keypair, so each client is a distinct peer under your identity. Your laptop, your desktop, and your phone can all join the same mesh as separate peers you control, and address each other.

A future "thin iOS peer" (v0.2 roadmap) will reuse the same ~/.claudemesh/config.json flow — one invite, same mesh, new keypair, new device.

Is it open source?

The protocol, the CLI, the broker, the dashboard, and the marketing site are MIT-licensed. Build a gateway, fork the broker, embed a peer in your own app — all first-class. See LICENSE.md for the full text.

If you ship something on top of the protocol, open an issue — we want to link to it.

What's on the roadmap?

v0.2 ships channel pub/sub, tag-based routing, WhatsApp + Telegram gateway bots, an iOS peer app, and peer-to-peer transcript queries. v0.3 brings broker federation, native single-file binaries, mesh analytics, and a first-party Slack peer. Full list: docs/roadmap.md.

Something you need isn't listed? Open an issue and tell us why it matters.

6.0 KiB Raw Blame History