Reference on Agent Mesh

agentmesh-node

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

agentmesh-node is the mesh member that runs beside an agent or a service.

agentmesh-node join [control-plane-url] [flags] enroll and store a credential
agentmesh-node run [flags] run the node
agentmesh-node forward egress://<name>:<port> [local-addr] forward a local TCP port to a named egress tunnel
agentmesh-node reset [--all] [--yes] forget the credential or everything
agentmesh-node state export|import <dir> move the identity to or from a state directory
agentmesh-node skill install|list|show manage the agent skill document

Files

The data directory is --data-dir if set, otherwise $AGENTMESH_DATA_DIR, otherwise the user configuration directory of the operating system (~/.config/agentmesh on Linux, ~/Library/Application Support/agentmesh on macOS). It is created with mode 0700 and holds:

agentmesh-control-plane

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

agentmesh-control-plane admits nodes, mints credentials, holds the mesh policy and tracks routers. It is an HTTP server over SQLite or PostgreSQL.

agentmesh-control-plane [flags] run the server
agentmesh-control-plane admin ban --peer <id> ban a node directly in the database
agentmesh-control-plane admin unban --peer <id> lift a ban

Flags

Flag	Default	Meaning
`--issuer`		OIDC issuer URL(s), comma-separated. At least one of `--issuer` or `--workload-issuer` is required. The first issuer is advertised to enrolling nodes on `/info`.
`--workload-issuer`		Workload OIDC issuer(s), comma-separated (`<issuer>` or `<issuer>=<email-suffix>`, such as `https://accounts.google.com=.gserviceaccount.com`). Automatically added to `--issuer`. Workload tokens can enroll, refresh, and exchange credentials (`/register`, `/refresh`, `/token/exchange`), and are refused at `/user/*` and `/oauth/authorize`.
`--allowed-audiences`	`agentmesh-audience`	Audiences accepted in OIDC tokens, comma-separated.
`--oidc-client-id`	first audience	OAuth client ID advertised on `/info`, for providers where it differs from the audience.
`--insecure-skip-tls-verify`	`false`	Skip TLS verification when fetching issuer metadata and keys. For a cluster issuer served with the cluster CA, or a local development issuer.
`--bind-address`	`0.0.0.0:8080`	HTTP listen address.
`--db-driver`	`sqlite`	`sqlite` or `postgres`.
`--db-dsn`	`control-plane.db`	Database DSN. A PostgreSQL DSN contains a password, so the next two options are preferred for PostgreSQL.
`--db-dsn-path`		File containing the DSN. Overrides `--db-dsn`. Can also be set with `AGENTMESH_DB_DSN`.
`--admin-token-path`		File containing the bearer token for `/admin/*` and `POST /policies`. Can also be set with `AGENTMESH_ADMIN_TOKEN`. Without a token, the admin API cannot be used.
`--auto-approve-enrollment`	`false`	Issue credentials for valid bootstrap-token enrollments immediately instead of queueing them for approval.
`--biscuit-ttl`	`24h`	Lifetime of each credential. If the OIDC token expires sooner, the credential expires with it.
`--oidc-session-ttl`	`2160h` (90 days)	How long a human OIDC enrollment may keep refreshing before the identity must log in again.
`--workload-session-ttl`	`48h`	How long a workload OIDC enrollment (`--workload-issuer`) may refresh without presenting a fresh platform JWT in `TokenRefreshRequest.jwt`.
`--key-rotation-interval`	`24h`	How often a new signing key is generated. `0` disables rotation.
`--key-grace-period`	`1h`	How long a rotated-out key stays accepted. Credentials signed by a retired key cannot be verified or refreshed. Nodes and routers must pull `/keys` well within this window (`agentmesh-node --control-plane-sync-interval`, `agentmesh-router --keys-sync-interval`).
`--lease-duration`	`15m`	How long a router lease lasts without renewal.
`--node-retention`	`720h` (30 days)	How long the record of an enrolled node is kept after its session expires. Banned nodes are kept forever. `0` keeps every record.
`--mesh-reconnect-interval`	`30s`	How often the event publisher re-reads the router leases and dials any router it is not connected to.
`--log-level`	`info`	`debug`, `info`, `warn`, `error`. `LOG_FORMAT=json` selects JSON output.

HTTP API

Every request and response is a message in api/agentmesh.proto, in one of two encodings. Routes that mesh components call use binary protobuf (application/x-protobuf). Routes for operators and the console use protojson of the same messages, with proto field names; unknown fields are rejected. POST /policies accepts either and answers in the encoding of the request.

agentmesh-router

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

agentmesh-router is a libp2p peer with a stable identity that new nodes connect to first. It hosts the DHT, relays traffic between nodes that cannot reach each other, and forwards the control plane’s signed events. It has no policy of its own.

agentmesh-router [flags]

Enrollment

A router enrolls like a node, requesting mesh:role:router, with one of:

Flag	Meaning
`--jwt-path`	File containing an OIDC token (a projected service account token, for example).
`--bootstrap-token-path`	File containing a bootstrap token minted with `"role": "mesh:role:router"`.
`--oidc-token`, `--bootstrap-token`	The same tokens as values. Visible in process listings. The file forms are preferred.

The mesh policy must bind the router’s identity to mesh:role:router. The agentmesh-p2p Helm chart handles this: its bootstrap job binds the router’s service account and mints a bootstrap token with max_usages equal to the replica count.

agentmesh-one

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

agentmesh-one runs a control plane, a router and the web console in one process on one port. The router’s libp2p transport is WebSocket on the same port as the HTTP API, so a node needs only one https URL. The same binary is also the admin client for a running instance.

agentmesh-one [flags] run the mesh
agentmesh-one token create|list|revoke|qr manage bootstrap tokens on a running instance
agentmesh-one admin ban <peer-id> ban a node

Files

Everything lives in --data-dir (default .): agentmesh.db (SQLite), the router key, join-token and admin-token when generated, and bin/ for a downloaded tunnel connector.

Node configuration file

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

agentmesh-node.yaml declares what a node is (labels), what it publishes (services), what it requires from callers (attenuation) and what it requires from providers (egress). Both agentmesh-node join and agentmesh-node run read it from --config, by default ./agentmesh-node.yaml. A missing file means an empty configuration. Unknown keys are an error, because a typo under attenuation would otherwise weaken the node without notice.

version: "v1alpha1"

labels:
 region: eu-west-1
 team: platform

services:
 - type: mcp
 name: code-reviewer
 description: "Reviews diffs"
 target_url: "http://127.0.0.1:7777/mcp"
 - type: mcp
 name: filesystem
 command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"]
 env:
 NODE_OPTIONS: "--max-old-space-size=256"
 - type: inference
 name: vllm
 target_url: "http://127.0.0.1:8000"
 target_auth_path: /etc/agentmesh/vllm-key
 - type: a2a
 name: triage
 target_url: "http://127.0.0.1:9999"

attenuation:
 rules:
 - 'maintenance() <- time($t), $t > 2026-12-31T00:00:00Z;'
 checks:
 - 'check if label("team", "platform");'
 policies:
 - 'deny if service("mcp", "filesystem"), group("contractors");'
 - 'deny if maintenance();'

egress:
 require_labels:
 jurisdiction: eu

`version`

"v1alpha1", or omitted (read as v1alpha1). A node refuses a version it does not know.

Mesh policy

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

The mesh policy is one document held by the control plane: a list of roles, a list of bindings and a list of egress destinations. It is posted as JSON (protojson of PolicyConfig in api/agentmesh.proto) to POST /policies, read back from GET /admin/policy, edited in the console, or given to agentmesh-one --policy-file for first boot.

{
 "roles": [
 {
 "name": "mesh:role:node",
 "allowed_services": ["system://mesh.catalog"],
 "allowed_labels": ["region=*", "team=platform"]
 },
 {
 "name": "developer",
 "allowed_services": ["mcp://code-reviewer", "mcp://build-runner.*", "inference://*"],
 "allowed_targets": ["group:dev-nodes", "node:12D3KooWSpecialNode"],
 "custom_datalog": ["tier(\"standard\");"]
 },
 {
 "name": "analyst",
 "allowed_services": ["egress://bigquery.googleapis.com"],
 "allowed_targets": ["*"],
 "http": [
 { "service": "egress://bigquery.googleapis.com", "methods": ["GET", "POST"], "paths": ["/bigquery/v2/projects/my-proj/datasets/*"] }
 ]
 }
 ],
 "bindings": [
 { "role": "mesh:role:node", "members": ["group:engineering", "user:system:serviceaccount:agentmesh-nodes:calc-mcp-agentmesh-node"] },
 { "role": "developer", "members": ["group:engineering"] },
 { "role": "analyst", "members": ["group:analytics"] }
 ],
 "egress": [
 {
 "name": "bigquery.googleapis.com",
 "served_by": ["site=eu"],
 "broker": {
 "oidc_federation": {
 "token_endpoint": "https://sts.googleapis.com/v1/token",
 "audience": "//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/agentmesh/providers/agentmesh-cp",
 "scopes": ["https://www.googleapis.com/auth/bigquery.readonly"]
 }
 }
 }
 ]
}

The whole document is replaced on every post. Unknown fields are rejected, so a misspelt key fails the request instead of dropping a grant without notice.

Node API

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

The local API that agentmesh-node run serves to agents, gateways, and scripts on the same machine or cluster. It is available on TCP (--bind-addr, default 127.0.0.1:8080) and on a Unix socket (--socket-path, default <data-dir>/agentmesh.sock). The Envoy ext_authz and ext_proc endpoints are served on the same listeners.

Authentication

Listener	Requirement
TCP (`--bind-addr`)	`X-Mesh-Authentication: Bearer <token>` on every request, or `Authorization: Bearer <token>` on non-proxy endpoints (`/mcp`, `/v1/`, `/egress/`, `/oauth/*`), or a client certificate when `--tls-ca` is set.
Unix socket (`--socket-path`)	None required for node-level access (the socket has mode `0600`). A caller may still pass an Agent Mesh Task Biscuit or platform JWT in `X-Mesh-Authentication` or `Authorization` to scope the request to that caller’s identity and task rules.

The bearer <token> accepted by agentmesh-node can be: