Concepts on SAM

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["sam-control-plane<br/>identity · policy · signing key"]
 DB[("database")]
 CP --- DB
 end
 IDP["identity provider<br/>(OIDC)"]
 R["sam-router<br/>bootstrap · relay · DHT"]
 A["sam-node A"]
 B["sam-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

sam-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. This page follows the credential from enrollment to expiry: how a node gets it, what it contains, how it is renewed, and how it is revoked.

Keys and peer IDs

The first thing a node does is generate an Ed25519 key pair and store it in its data directory (~/.config/sam-mesh/agent.db by default). Its peer ID, the 12D3KooW... string that appears in logs, discovery results and proxy URLs, is derived from the public key. The key never leaves the machine. The credential is bound to the key, so a copied credential is useless without it, and every peer-to-peer connection proves possession of the key as part of the libp2p handshake.

Authorization

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

Authorization in SAM answers one question: may this caller use this service on this node? Three sources contribute to the answer, and the node that hosts the service combines them: the caller’s credential, the mesh policy, and the node’s own configuration. Each source can only narrow what the others allow. If none of them grants access, the answer is no.

Services are the unit of authorization

A node publishes services, each with a type and a name: mcp://calculator, inference://vllm-eu, a2a://triage, and the built-in system://sam.catalog that answers discovery queries. Policy grants access to services by these names. It does not look inside a service: a grant on mcp://db offers every tool that the MCP server exposes. To offer different privilege levels, publish different services (mcp://db-reader, mcp://db-writer) and grant them separately. Choosing which tools a backend exposes is the job of the backend, or of a small MCP server placed in front of it.

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 sam-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-Sam-Authentication: Bearer <token>.
A Unix socket, <data-dir>/sam.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. SAM 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.