Mirror Frame Protocol

Mirror Frame Protocol (MFP) is a protocol and runtime for secure, peer-to-peer communication between autonomous agents. It provides end-to-end encrypted channels, federated message transport, and a minimal API for agent lifecycle management.

• Symmetric design — no client/server distinction, all agents are peers
• End-to-end encryption — ChaCha20-Poly1305 AEAD with X25519 key exchange
• Federation-ready — bilateral channels, recovery protocols, TCP transport
• Production hardening — circuit breakers, timeouts, health checks, metrics
• High performance — Merkle tree for O(log N) global state updates
• Library-first — runtime embeds in any Python process
• Standalone server — YAML-configured process for managing agents
• Type-safe — full type annotations with py.typed marker

Installation

pip install mfp

Or install from source:

git clone https://github.com/madahub/mirror-frame-protocol.git
cd mirror-frame-protocol
pip install -e .

Quickstart

5-minute hello world between two agents:

from mfp import Runtime, RuntimeConfig, bind, mfp_send, mfp_channels

# Create a runtime
config = RuntimeConfig()
runtime = Runtime(config)

# Define two simple agent callables
def alice(channel_id, message):
    print(f"Alice received: {message.decode()}")
    return {"status": "ok"}

def bob(channel_id, message):
    print(f"Bob received: {message.decode()}")
    return {"status": "ok"}

# Bind agents to the runtime
alice_handle = bind(runtime, alice)
bob_handle = bind(runtime, bob)

# Establish a channel between them
alice_handle.establish_channel(bob_handle.agent_id, symmetric_key=None)

# Send a message from Alice to Bob
channels = mfp_channels(alice_handle)
channel_id = channels[0].channel_id

receipt = mfp_send(
    alice_handle,
    channel_id=channel_id,
    plaintext=b"Hello from Alice!"
)

print(f"Message sent, receipt: {receipt.message_id.hex()[:16]}...")

# Shutdown
runtime.shutdown()

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Application                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Public API: Runtime, bind/unbind, mfp_send/channels/status │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   ┌─────────┐         ┌─────────┐        ┌──────────┐
   │ Runtime │◄────────┤  Agent  │◄───────┤ Storage  │
   │ Pipeline│         │Lifecycle│        │  Engine  │
   └─────────┘         └─────────┘        └──────────┘
        │                                       │
        ▼                                       ▼
   ┌─────────┐                            ┌──────────┐
   │  Core:  │                            │Federation│
   │ Crypto, │                            │Transport │
   │ Frames  │                            └──────────┘
   └─────────┘

Layers:

• Core — cryptographic primitives, frame construction/validation
• Runtime — agent callable pipeline, hooks, error handling
• Agent — lifecycle management (bind/unbind), tool interface
• Storage — persistent state, message queues, channel records
• Federation — bilateral channels, recovery, wire protocol, TCP server

Documentation

• Quickstart Guide — step-by-step tutorial
• Architecture — design deep-dive
• Security Model — threat model and guarantees
• API Reference — library interface documentation
• Production Guide — deployment and operations
• Federation — multi-runtime protocol

Project Status

Version: 0.4.0 (Production Ready)

All implementation phases complete including production hardening:

• P0: Critical Security
• P1: Operational Robustness (logging, health checks, metrics, limits)
• P2: Performance Optimization (Merkle tree, circuit breakers, timeouts, pooling)
• P3: Advanced Hardening (frame caching, key rotation, deduplication)

Test Coverage: 813 tests passing (591 unit, 191 integration, 27 E2E, 4 benchmark)

License

Apache License 2.0 — see LICENSE for details.

Credits

MFP — authored by Akil Abderrahim and Claude Sonnet 4.5

---

For protocol design documentation, see the design specifications.