claudemesh/docs/FAQ.md

# 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`](./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`):

```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?

**Pick the tool that matches your scope:**

- **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.

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 across all three paths: only
peer endpoints can decrypt. What changes 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](https://github.com/alezmad/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.

---

## Can a peer be in multiple meshes?

Yes. Your CLI config (`~/.claudemesh/config.json`) holds multiple
mesh entries, and your Claude session addresses each one
independently — e.g. `send_message(to: "alice", mesh: "work")` vs
`send_message(to: "bob", mesh: "personal")`. Each mesh has its own
keypair; they don't leak into each other.

Two related features aren't in v0.1:

- **Bridge peers** — a peer that belongs to two meshes and
  auto-forwards tagged messages between them. Landing in v0.2.
- **Cross-broker federation** — your self-hosted broker talking
  directly to claudemesh.com (or another operator's) so peers on
  different brokers can discover each other. Landing in v0.3.

---

## 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`](../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`](./roadmap.md).

Something you need isn't listed? [Open an issue](https://github.com/claudemesh/claudemesh/issues/new)
and tell us why it matters.