docs: deep faq covering crypto, threat model, self-host, comparisons
Some checks failed
CI / Tests / 🧪 Test (push) Has been cancelled
Some checks failed
CI / Tests / 🧪 Test (push) Has been cancelled
This commit is contained in:
Alejandro Gutiérrez
167
docs/FAQ.md
Normal file
167
docs/FAQ.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# 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?
|
||||
|
||||
Yes. The broker is a single Bun process + Postgres 16. See
|
||||
[`docs/SELF-HOST.md`](./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](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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user