zahadun
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zahadun @bob audit the SEO of example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
-pmode. If you pay for Claude Code, your mesh costs nothing extra.One conversation, two machines. The A2A
contextIdis 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
@peeraddressing. AUserPromptSubmithook 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 --rebasenever 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 getclientAuth-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.
Related MCP server: claudemesh
Architecture in five decisions
The router is a human. Pure A2A: addressing means choosing a peer. No broadcasts, no capability matching. You say
@bob, code delivers to bob.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
--resumework.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.The risky part is code; the convenient part is the model. Delivery and addressing: hook, deterministic. Result pickup, catalogs, memory: MCP tools, model-driven.
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 anX-Zahadun-Traceheader; 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 configsEverything 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 |
| who is in the mesh, what they can do (live AgentCards) |
| delegate; returns a task id |
| poll result / status |
| live model catalog of the local OpenCode engine |
| 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.
Available Tools
8 toolszahadun_askA
Zleca zadanie peerowi w siatce. Zwraca identyfikator zadania - wynik odbierz przez zahadun_task. temat to contextId (UUID) wspolny dla sesji na obu maszynach; pominiety - zostanie wygenerowany.
Inputs: peer (required), zadanie (required), model, temat, +1 more. Returns: result
zahadun_memory_readC
Odczyt tematu (po contextId) albo wpisu wspolnego (po slugu).
Inputs: temat (required), tor. Returns: result
zahadun_memory_searchA
Przeszukuje pamiec mesh po tresci (ripgrep po katalogu toru).
Inputs: fraza (required), tor, temat. Returns: result
zahadun_memory_topicsC
Lista tematow i wpisow wspolnych w pamieci mesh.
Inputs: tor. Returns: result
zahadun_memory_writeA
Zapis do pamieci mesh. temat to contextId biezacego tematu albo slug wiedzy ponad tematami (wtedy ustaw wspolne=true). Tworzy nowy plik - nigdy nie nadpisuje cudzych wpisow.
Inputs: temat (required), tresc (required), tor, tagi, +2 more. Returns: result
zahadun_modelsA
Zywy katalog modeli toru opencode wraz z cenami (z lokalnego serwera OpenCode). Model spoza katalogu jest bledem, nigdy cichym podstawieniem.
Inputs: no named parameters. Returns: result
zahadun_peersC
Kto jest w siatce zahadun i co umie (z AgentCards).
Inputs: odswiez_karty. Returns: result
zahadun_taskA
Odbior wyniku lub statusu zadania. id w formacie 'peer:taskId' (tak jak zwrocil zahadun_ask).
Inputs: id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct function: peer discovery, task submission, task status retrieval, model catalog, memory search, read, write, and topic listing. There is no overlap between task and memory operations, and request/response pair (ask/task) is clearly separated.
All tools share the 'zahadun_' prefix, and the memory tools follow a 'memory_<action>' pattern. However, some names are bare nouns (peers, task, models) while others are verbs (ask) or compound nouns (memory_topics), creating minor inconsistency in naming style.
With 8 tools, the set is well-scoped for the server's purpose of managing an agent mesh network, task delegation, and shared memory. Each tool serves a clear role without redundancy or bloat.
Core workflows are covered: task lifecycle (submit, retrieve status/result), peer discovery, and memory operations (write, read, search, list). Minor gaps exist such as no task cancellation or listing of all tasks, but these are not essential for the primary use case.
Related MCP Connectors
Private networking for AI agents: networks, nodes, commands, files, services via hosted MCP.
Use your own Windows, Mac or Linux computer from ChatGPT, Claude, Cursor or Gemini CLI: run commands, read, write and search files, run long processes. Your computer only makes an outgoing connection (no open ports or VPN). Read-only mode, allowed folders, blocked commands and an action log keep you in control. Free plan available.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Gives AI agents a public IPv6 identity, hostname, port forwarding, web fetch, team mesh. Free tier.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables peer-to-peer communication, discovery, shared state, and file coordination between AI coding agents across machines and sessions.11 npm17Elastic 2.0
- FlicenseNot gradedqualityBmaintenanceEnables Claude Code agents to communicate and share context across sessions via a peer-to-peer mesh, allowing them to ask for help from other agents without human interruption.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to orchestrate a heterogeneous machine fleet via SSH, with unified command execution, file transfer, and dispatch of coding agents across platforms.2Apache 2.0
- AlicenseBqualityDmaintenanceAgent-native SSH control plane with a local Web Terminal, human-in-the-loop secret input, keychain-backed profiles, and user-confirmed uploads for Codex, Claude Code, and MCP-compatible coding agents.181Apache 2.0