Concepts on Agent Mesh

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

An agent mesh has a small control plane, one or more routers, and any number of nodes. The control plane decides who is in the mesh and what they may do. Routers make the nodes reachable. Nodes do the work: they publish services and call each other’s services on behalf of the agents next to them.

flowchart LR
 subgraph cp["control plane"]
 CP["agentmesh-control-plane<br/>identity · policy · signing key"]
 DB[("database")]
 CP --- DB
 end
 IDP["identity provider<br/>(OIDC)"]
 R["agentmesh-router<br/>bootstrap · relay · DHT"]
 A["agentmesh-node A"]
 B["agentmesh-node B"]
 AG["agent"]
 SVC["your tool or model"]

 CP -. verifies tokens .-> IDP
 R -- lease --> CP
 A -- enroll / refresh --> CP
 B -- enroll / refresh --> CP
 A <--> R
 B <--> R
 A <-. direct when possible .-> B
 AG -- "MCP · OpenAI API<br/>(local)" --> A
 B --- SVC

The control plane

agentmesh-control-plane is an HTTP service backed by SQLite or PostgreSQL. It is the only component that has to be trusted. It is not on the data path: tool calls and model requests never pass through it.

Identity and enrollment

Mon, 01 Jan 0001 00:00:00 +0000

Every participant in a mesh, node or router, has a key that it generated itself and a credential that the control plane issued for that key. Callers that reach the mesh through a node (workloads, users, and sandboxed agents) exchange their platform JWTs into delegated credentials bound to that node’s channel, and narrow them offline per task. This page follows credentials from enrollment and exchange to attenuation, outbound federation, renewal, and revocation.

Authorization

Mon, 01 Jan 0001 00:00:00 +0000

Authorization in Agent Mesh answers one question: may this caller perform this operation on this service on this node right now? Four sources contribute to the answer, and the destination node combines them:

The caller’s credential (Block 0 authority facts signed by the control plane).
The standing mesh policy (roles, bindings, HTTP narrowings, and egress destinations distributed by the control plane as Datalog rules).
Any appended TaskAuthorizationRule blocks (tar_block) on the credential, which narrow authority for a specific task or sub-agent hop.
The hosting node’s local attenuation configuration.

Each layer can only narrow what the others allow. If standing policy or any appended task block denies the request, the answer is no.

Networking and the node API

Mon, 01 Jan 0001 00:00:00 +0000

This page follows a request from an agent to a service on another node: how the calling node finds the provider, how the two connect, and what the agent sees at each end.

The node’s local API

An agent does not speak to the mesh directly. It speaks to the agentmesh-node on its own machine, through one of two listeners:

TCP, 127.0.0.1:8080 by default (--bind-addr). Every request must carry the node’s API token as X-Mesh-Authentication: Bearer <token>.
A Unix socket, <data-dir>/agentmesh.sock by default (--socket-path), created with mode 0600. No token is needed, because only the user who owns the socket can open it. docker.sock works the same way.

You can turn either listener off by passing an empty value. With --bind-addr=, the node has no listening port and no secret to manage. This is a good setup when everything that uses the node runs as the same user.

Control and data boundaries

Mon, 01 Jan 0001 00:00:00 +0000

When you run your own control plane, you decide everything about the mesh. On the public testnets, someone else decides who joins and what the policy says. This page lists the decisions that become yours in a dedicated deployment and the mechanism that enforces each of them.

What you control in a dedicated deployment

Membership. Enrollment goes through your identity provider or through bootstrap tokens that you mint. The bindings in the control plane decide which identities receive which roles. An identity without a binding cannot enroll a node.
The signing key. The control plane generates its Ed25519 signing keys and stores them in its database. Every credential in the mesh is signed by one of these keys, and nobody outside the deployment can mint or extend a credential. The keys rotate on the schedule you set.
The policy. What each role may call, on which nodes and with which labels, is stored in your database. It can only be changed with your admin token or through your console.
Revocation. A ban takes effect on the next credential refresh (within the credential TTL, 24 hours by default) and, through the mesh event channel, immediately on every connected node.
Where the software runs. Agent Mesh is Apache-2.0, sends no telemetry, and does not depend on any hosted service. The control plane, routers and nodes run wherever you put them: a laptop, a private cluster, an air-gapped network.

The public testnets give you none of this. They are useful for trying the software. Do not put anything there that you would not publish.