Install on one machine. Or all of them.

Prerequisites

Single-machine install

Pick your platform. Each path lands you with the local sidecar running and the MCP server ready to accept agent connections.

First-run setup

{
  "mcpServers": {
    "potluck": {
      "command": "curl",
      "args": ["-s", "http://127.0.0.1:8321/mcp/sse"]
    }
  }
}

Restart Claude Code. The agent should now see memory_search, memory_save, task_create, and the other Potluck MCP tools. Ask the agent to remember something. Confirm it shows up in Potluck's memory browser.

Cross-machine memory aggregation (optional)

1. Verify mesh connectivity

Find each machine's mesh IP via tailscale status. From one machine, ping another:

ping <peer-mesh-ip>

2. Opt in on each machine

Set POTLUCK_PEER_MEMORY_ENABLED=1 in the sidecar's environment. Persistent per OS:

macOS

launchctl setenv POTLUCK_PEER_MEMORY_ENABLED 1, then add the same export to ~/.zshenv for persistence. Restart Potluck.

Linux

Add Environment="POTLUCK_PEER_MEMORY_ENABLED=1" to your systemd user unit's [Service] section. systemctl --user daemon-reload && systemctl --user restart potluck-sidecar.

Windows

Edit the launcher .bat file to add set POTLUCK_PEER_MEMORY_ENABLED=1 before the python launch line. Restart Potluck.

3. Verify the wire works

From your machine, hit the peer:

curl -s -X POST http://<peer-mesh-ip>:8321/peer/memory/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"how do I configure nginx","limit":10}'

Three normal outcomes: {"memories":[],"count":0} means the wire works and the peer has no matching memories.{"memories":[...],"count":N} means the wire works and the peer has results.{"detail":"Peer memory search is opt-in..."} means you forgot the env var on that peer.

First peer call may take 15-30 seconds while the bge-small embedder lazy-loads. Subsequent calls are <50 ms.

Five-minute smoke test

If all five pass, the architecture is live for you.

1. Sidecar running locally: `curl 127.0.0.1:8321/health` returns 200.
2. Sidecar reachable from a peer: `curl <peer-mesh-ip>:8321/health` returns 200.
3. Opt-in env var set on the peer: `curl -X POST <peer-mesh-ip>:8321/peer/memory/search -H "Content-Type: application/json" -d '{"query":"hello"}'` returns 200 (not 503).
4. Save a memory on the peer through your local agent.
5. Query the same content from your machine via /peer/memory/search. The memory you saved on the peer comes back across the mesh.

Honest limits

• Opt-in is all-or-nothing per machine. When you set the env var, peers can search the entire memory store of that machine. Per-project sharing flags are roadmap (v0.5+).
• Trust = mesh-IP reachability. Anyone who can dial your mesh IP can call the peer endpoint if you opted in. Signed-nonce challenge replacing mesh-IP-as-credential is v0.5+.
• Read-only. Peers can query your memories but cannot write to them. Memory writes stay strictly local even when peer aggregation is enabled.
• No graceful federation yet. If you query Mac and it forwards to Linux, you get Linux's results back. Mac's local results merged with Linux's requires client-side aggregation today; the peer-aware retriever is roadmap.
• No auto-update channel yet. When you want to update, download the new release and reinstall.
• Public membership is not open. This guide is for pre-launch private beta.

Where to go next

• /benchmarks · measured numbers across memory retrieval, inference, and cross-machine peer retrieval on Mac/Linux/Windows.
• /manifesto · why Potluck is built as a member-operated network and a founder-led company.
• /roadmap · what is shipped, in flight, designed, and to be decided.
• Deeper install + troubleshooting docs (auto-start on boot per OS, full troubleshooting catalog, architecture invariants) live in the repository at docs/install.md.