zahadun

A self-hosted mesh of full-peer AI agents — Claude Code and OpenCode talking across your machines over A2A, with real mTLS identity and no API keys.

Every machine is an equal peer: it can ask (an MCP bridge inside Claude Code / OpenCode) and answer (an A2A server executing tasks with the local claude CLI, OpenCode, or plain scripts). There is no controller node, no cloud relay, and no per-token billing — the Claude track runs on your existing subscription via claude -p.

you, on machine A                                machine B
┌───────────────────────┐                        ┌───────────────────────┐
│ Claude Code / OpenCode│   A2A JSON-RPC         │ reverse proxy :8443   │
│   │ MCP bridge        │ ──────────────────────▶│   mTLS, CN → identity │
│   ▼                   │   over WireGuard mesh  │   ▼                   │
│ "@bob audit the SEO   │   (NetBird/Tailscale)  │ A2A server :9990      │
│  of example.com"      │                        │   ├─ script           │
│                       │◀── task id, then ──────│   ├─ claude -p        │
│ zahadun_task(id)      │    artifacts           │   └─ opencode         │
└───────────────────────┘                        └───────────────────────┘

Why this exists

Multi-machine agent collaboration is a frequently requested capability. The pieces all exist — A2A↔MCP bridges, WireGuard meshes, workload identity (SPIFFE), agent memory servers — but as separate, mostly cloud- or Kubernetes-shaped projects. zahadun is the whole thing in ~1,500 lines of Python with two dependencies (httpx, mcp), sized for one operator and a handful of machines.

What's different here

• Subscription, not API keys. The Claude executor is the CLI in -p mode. If you pay for Claude Code, your mesh costs nothing extra.
• One conversation, two machines. The A2A contextId is the Claude session UUID on every machine in a task's path. claude --resume <id> on either end shows that machine's half of the same conversation.
• Deterministic @peer addressing. A UserPromptSubmit hook parses mentions before the model sees the prompt. Routing is code, not an LLM decision: unknown peer → hard block with the roster; unreachable peer → the prompt never reaches the local model (you can't mistake a local answer for the peer's).
• Conflict-free mesh memory, no database. Shared memory is a git-synced directory of markdown files named <peer>-<timestamp>.md. A peer only ever creates its own files, so replication can't conflict — git pull --rebase never meets a merge.
• Real identity, home-lab sized. mTLS everywhere; each machine's cert is signed by your own root CA (an OpenBao PKI mount works well — see docs/CA-RUNBOOK.md). CSR authenticity is attested with an SSH signature (ssh-keygen -Y) from the operator's personal key. Client-only machines get clientAuth-only certs: even a stolen key can't impersonate a server.
• Honest cards. A peer's AgentCard lists only skills that work today. A planned skill is a promise the caller can't distinguish from a working one — they just get FAILED.

Architecture in five decisions

1. The router is a human. Pure A2A: addressing means choosing a peer. No broadcasts, no capability matching. You say @bob, code delivers to bob.
2. Tracks are pure end-to-end. A task submitted from Claude Code executes in Claude on the target; OpenCode-to-OpenCode likewise. Mixing tracks would orphan the session history that makes --resume work.
3. The bridge has no model. The MCP server is an HTTP client plus a file layer. All intelligence lives in the tool that loaded it or on the target peer. It detects its own track from the MCP handshake's clientInfo.
4. The risky part is code; the convenient part is the model. Delivery and addressing: hook, deterministic. Result pickup, catalogs, memory: MCP tools, model-driven.
5. Peer input is untrusted. The Claude executor runs headless with no tools by default (permission prompts auto-deny). You grant tools per skill, explicitly, in skills.json. Loops are cut by an X-Zahadun-Trace header; caller identity comes from the client cert's CN via the proxy — never from the request body.

Quick start

See INSTALL.md. The short version, per machine:

# module
python3 -m venv /opt/zahadun-a2a/venv
/opt/zahadun-a2a/venv/bin/pip install zahadun-a2a   # or from a checkout

# client side (every machine): MCP bridge + @peer hook
claude mcp add zahadun --scope user -- /opt/zahadun-a2a/venv/bin/python -m zahadun_a2a.mcp
# + hook in ~/.claude/settings.json, + block in opencode.json  → INSTALL.md

# server side (machines that answer): systemd unit + reverse proxy with mTLS
# examples/ has units and nginx/Apache/Caddy configs

Everything runs as a regular user. No dedicated system account, no root services — the Claude executor needs the user's ~/.claude anyway.

MCP tools exposed to your agent

tool	purpose
zahadun_peers()	who is in the mesh, what they can do (live AgentCards)
zahadun_ask(peer, task, …)	delegate; returns a task id
zahadun_task(id)	poll result / status
zahadun_models()	live model catalog of the local OpenCode engine
zahadun_memory_search/read/write/topics	shared mesh memory

Status

Working: the full client+server loop, three executors (script / claude -p --session-id / OpenCode prompt_async with a model-fallback ladder), task persistence across restarts, audit log, loop detection.

Not yet: SSE streaming (cards honestly say streaming: false), input-required pauses (skills marked as needing human confirmation are refused, not hung), per-caller rate limits.

Security model

Read SECURITY.md before exposing anything. Summary: designed for a single operator's machines on a private WireGuard mesh; peers are semi-trusted (authenticated, but their task content is not); it is not a multi-tenant system and was never designed as one.

A note on language

The project was built for a Polish-speaking mesh: code comments, error messages and some config keys (drabina = model ladder, wykonawca = executor, potwierdzenie_czlowieka = human confirmation) are Polish. The docs you're reading, the wire protocol (A2A v1.0) and the MCP tool names are English. Translating internals is on the table if anyone actually needs it — open an issue.

License

Apache-2.0.