# IronMesh

> Zero-config, end-to-end encrypted agent-to-agent communication that never leaves your local network. No cloud. No internet. No compromises.

IronMesh is an open-source Python agent mesh protocol that lets AI agents on the same LAN (or the same LoRa radio network) discover each other, mutually authenticate, and exchange encrypted messages without any cloud dependency. It fills the gap between agent-to-tool protocols like MCP and cloud-based agent-to-agent APIs like Google A2A: peer-to-peer, offline-capable, end-to-end encrypted, and self-hosted.

Current release: # V:version_tag #v0.9.4.1# /V # (April 2026). License: MIT. # V:tests_passing #1068# /V # tests green on Ubuntu + Windows + macOS, Python 3.10–3.13. Project home: https://github.com/WizTheAgent/IronMesh.

## What it is

- **Transport-agnostic protocol.** Runs over WebSocket on a LAN, Reticulum over LoRa radio, or any mix. Multi-hop mesh routing (distance-vector, split horizon) bridges transports automatically.
- **Zero-config discovery.** mDNS auto-discovers peers on the LAN. Identity keys exchanged only inside an authenticated handshake.
- **End-to-end encryption.** NaCl / libsodium primitives — same stack as Signal and WireGuard. X25519 ECDH for session keys, XSalsa20-Poly1305 (SecretBox) for payloads, Ed25519 signatures per frame.
- **Forward secrecy.** Ephemeral X25519 keypairs per session + per rekey; private keys wiped from memory immediately after the shared secret is derived.
- **TOFU identity pinning + capability-set binding** (v0.8.5.6+). First-contact trust model for peer identity; a canonical SHA-256 hash of each peer's advertised capabilities is also pinned, so a peer that reconnects with changed capabilities auto-demotes to `pending-cap-change` until an operator reviews.
- **Tamper-evident audit log.** Every security-relevant event is HMAC-chain-linked; verification fails from any tampering point forward.
- **Cross-transport replay detection.** A duplicate frame arriving via a different transport than the original (e.g. WebSocket then Reticulum) fires a dedicated audit event.
- **Agent framework adapters.** LangChain + CrewAI + AutoGen adapters ship with IronMesh. TypeScript client with TOFU pin enforcement. # V:mcp_tools #25# /V #-tool MCP server for Claude Desktop / Claude Code integration.
- **OpenClaw channel plugin** (v0.9.0+). `@wiztheagent/openclaw-ironmesh@0.2.0` registers IronMesh as a first-class chat channel inside an OpenClaw 2026.3.x gateway: mesh peers appear as contacts, and outbound replies go back over the encrypted mesh.
- **Agent Client Protocol (ACP) stdio adapter** (v0.9.0+). `ironmesh-acp` speaks JSON-RPC 2.0 over NDJSON per `acp-core-v1@0.3.0`. Any ACP-compatible client (`acpx`, `codex`, `claude`, `droid`) can prompt remote mesh peers as if they were local agents.
- **Agent-to-Agent (A2A) HTTP gateway** (v0.9.0+). `ironmesh-a2a` exposes each mesh node as an A2A v0.3.0 peer with `/.well-known/agent-card.json`, `/a2a/jsonrpc`, and `/a2a/v1/inbox` endpoints. Bearer-token auth and anti-loop via `route_path` + `hop_count`.

## What it is NOT

- **Not an anonymity system.** LAN observers can see that two nodes communicate; they just can't read the payloads. If you need traffic-analysis resistance, use a mixnet, not IronMesh.
- **Not a WAN protocol.** IronMesh is designed for local-first deployments (LAN, LoRa mesh, air-gapped labs). WAN transport is technically possible but out of the v0.8.x scope.
- **Not a replacement for MCP.** MCP connects agents to tools; IronMesh connects agents to each other. They compose — # V:mcp_tools #25# /V # MCP tools ship in IronMesh for operator control.

## Quickstart

```bash
pip install ironmesh
ironmesh setup      # first-run wizard: generates identity keys in OS keychain
ironmesh run        # starts daemon on :8765 + dashboard on :8766
```

Or via Docker:

```bash
docker pull wiztheagent/ironmesh:# V:version #0.9.4.1# /V #
```

Two machines on the same LAN running `ironmesh run` will discover each other, handshake, and start exchanging encrypted messages automatically.

## Typical use cases

- **Homelab AI mesh** — Raspberry Pi running Ollama talks to a desktop coding agent and a phone-based assistant. No cloud, no API keys, no third parties.
- **Off-grid / LoRa deployments** — agents coordinate over sub-kbps radio links. Designed for remote fieldwork, disaster comms, prepper infrastructure.
- **Air-gapped labs** — security-critical environments where no process should ever touch the public internet.
- **Agent-framework integration** — drop IronMesh underneath LangChain / AutoGen / CrewAI to get TOFU-pinned peer-to-peer messaging without changing prompt logic.

## Key documents

- [README](https://github.com/WizTheAgent/IronMesh/blob/main/README.md) — project overview, install, first run
- [Getting Started](https://github.com/WizTheAgent/IronMesh/blob/main/GETTING_STARTED.md) — walkthrough from install to first multi-node handshake
- [Protocol specification](https://github.com/WizTheAgent/IronMesh/blob/main/docs/PROTOCOL_SPEC.md) — wire format, message types, state machine
- [Trust binding design](https://github.com/WizTheAgent/IronMesh/blob/main/docs/TRUST_BINDING.md) — capability-set pinning threat model + implementation
- [Security model](https://ironmesh.org/security.html) — threat model, primitives, what's in / out of scope
- [Changelog](https://github.com/WizTheAgent/IronMesh/blob/main/CHANGELOG.md) — every release since v0.5
- [Configuration reference](https://github.com/WizTheAgent/IronMesh/blob/main/docs/CONFIGURATION.md) — CLI flags, env vars, file paths, profile presets
- [Observability guide](https://github.com/WizTheAgent/IronMesh/blob/main/docs/OBSERVABILITY.md) — Prometheus metrics, structured JSON logs, OpenTelemetry, audit-log inspection

## How it compares

- **vs. Google A2A** — A2A requires HTTPS and internet; IronMesh works offline. A2A has no mesh routing; IronMesh does multi-hop.
- **vs. Anthropic MCP** — MCP connects agents to tools; IronMesh connects agents to each other. They compose — # V:mcp_tools #25# /V # MCP tools ship with IronMesh for operator control.
- **vs. Reticulum** — Reticulum is an excellent radio-first mesh layer; IronMesh uses it as one of its transports and adds per-agent identity, capability discovery, TOFU pinning, and an authenticated handshake on top.
- **vs. libp2p** — libp2p is great for p2p application networking but has no agent-specific surface (no cap discovery, no MCP, no pending-trust gate); IronMesh targets agent-to-agent specifically.
- **vs. NATS JetStream** — NATS requires a broker; IronMesh is broker-less. NATS is cloud-native; IronMesh is local-first.

## Maintainer

Project: https://github.com/WizTheAgent/IronMesh
Contact: info@ironmesh.org
Security reports: info@ironmesh.org (see SECURITY.md)