Mesh Networking

Akshi nodes can discover each other and sync agent state over a peer-to-peer mesh. The mesh uses three discovery mechanisms and two transport modes, selected automatically based on network topology.

Discovery mechanisms

mDNS (local network)

Nodes on the same LAN broadcast _akshi._tcp.local mDNS service records. This enables zero-configuration discovery — start two Akshi nodes on the same network and they find each other automatically.

WireGuard tunnels (point-to-point)

For nodes separated by NATs or firewalls, Akshi establishes WireGuard tunnels. Each node’s WireGuard public key is part of its peer configuration. Tunnels provide encrypted, authenticated transport without exposing dashboard ports to the public internet.

Kademlia DHT (wide-area)

For discovery beyond the local network without pre-configured peers, Akshi uses a Kademlia distributed hash table. Nodes publish their DID and endpoint information to the DHT and query it to find peers.

Peer configuration

Each peer entry includes:

Peers can be configured explicitly in runtime.toml or discovered via mDNS/DHT.

Transport selection

The runtime auto-detects the available transport:

• Peers configured (explicit or discovered) → HTTP transport. Sync envelopes are exchanged via POST /api/v1/sync/envelopes on each peer’s dashboard endpoint.
• No peers configured → Filesystem transport. Sync data is written to a shared directory, useful for single-node setups or development.

You do not choose the transport manually. The runtime picks HTTP when it has peers and falls back to filesystem otherwise.

What flows over the mesh

The mesh carries:

• Journal sync envelopes — Automerge CRDT changes for agent state convergence.
• Discovery announcements — node DID, capabilities, available agents.
• A2A messages — agent-to-agent communication across nodes.

The mesh does not carry inference requests, secrets, or raw credentials. Those stay local to each node.