mesh-peer-registry

A small, shared, language-agnostic peer registry for the mesh network used by hermes-mesh and openclaw-mesh.

Peers register with an Ed25519 public key and a webhook URL, then discover each other over a simple HTTP API. The server never holds private keys.

About

mesh-peer-registry provides a centralized but state-light way for mesh agents to announce themselves to one another:

• Peers register an Ed25519 public key and a webhook URL under a unique name.
• Registration, deregistration, and refresh requests are signed by the peer's private key, so the registry can trust the public key it stores.
• Other peers query the registry to find a recipient's webhook URL and public key.
• Mesh messages are signed by the sender and verified by the receiver against the sender's public key from the registry.

The signing protocol uses compact, deterministic, sorted-key JSON, making it straightforward to implement in other runtimes (e.g. the Node.js implementation in openclaw-mesh).

Features

• HTTP API for register, list, get, refresh, and deregister operations.
• Ed25519 signatures on all mutating requests.
• SQLite-backed store by default, with the path configurable via --store.
• TTL + reaper — peers can register with a TTL in seconds; a background reaper removes expired peers and refreshes keep them alive.
• CLI server launcher.
• Python client (RegistryClient) with built-in signing.
• No private keys kept by the registry.

Quick start

Install and run the server:

pip install mesh-peer-registry
mesh-peer-registry --port 8646 --store ~/.mesh/registry.sqlite

The server will listen on http://127.0.0.1:8646 and store peers in ~/.mesh/registry.sqlite.

CLI options

API

All registration, refresh, and deregistration requests must include a valid Ed25519 signature in the X-Mesh-Signature header over the sorted JSON body (or the action payload for refresh/deregister).

Python client

from mesh_peer_registry.crypto import generate_keypair
from mesh_peer_registry.client import RegistryClient

private, public = generate_keypair()
client = RegistryClient("http://127.0.0.1:8646", private, public)

client.register(
    "agent0",
    "http://127.0.0.1:8645/mesh/receive",
    role="operator",
    description="Hermes operator node",
    ttl=3600,
)

print(client.list_peers())

# Keep the registration alive before the TTL expires.
client.refresh("agent0")

# Later, deregister.
client.deregister("agent0")

Verifying a message

Receivers fetch the sender's public key from the registry and verify the X-Mesh-Signature header:

from mesh_peer_registry.crypto import verify_message
from mesh_peer_registry.client import RegistryClient

client = RegistryClient("http://127.0.0.1:8646", "", "")
peer = client.get_peer("agent0")

# body is the raw request body; signature is from the X-Mesh-Signature header.
ok = verify_message(peer.public_key, body, signature)

When X-Mesh-Timestamp is included in the signed payload (optional, controlled by MESH_SIGN_TIMESTAMP on the sender), the receiver should prepend f"{timestamp}\n" to the body before verification. Backward-compatible receivers try both forms.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT