Guides on Agent Mesh

Exposing services

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

A node does not publish any service by default. You declare the services it offers in agentmesh-node.yaml. This guide covers the three kinds of service a node can serve and what the mesh policy must contain before anyone can reach them.

The configuration file

agentmesh-node reads agentmesh-node.yaml from the working directory, or the file named by --config. Both join and run read it, because labels are declared at enrollment. A minimal file with one service:

Connecting agents

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

An agent uses the mesh through the agentmesh-node that runs on its own machine. The node is an MCP server, so you can point any MCP client at it. This guide gives the configuration for the common clients and explains what the agent gets.

What every client needs

Three values, all printed by agentmesh-node run --daemonize:

The endpoint: http://127.0.0.1:8080/mcp (Streamable HTTP).
The token: the contents of ~/.config/agentmesh/api-token, or the AGENTMESH_API_TOKEN you started the node with. It goes in the header X-Mesh-Authentication: Bearer <token>.
The socket: ~/.config/agentmesh/agentmesh.sock. Anything the agent runs in a shell can use the socket without a token. This is the easier way to reach the node’s /v1 inference endpoint from scripts.

The node must be running before the client starts. MCP clients start and manage stdio servers themselves, but agentmesh-node is an HTTP server that they connect to. You can run agentmesh-node run --daemonize as often as you like, so it is safe to put it in a shell profile or to let the agent run it.

Reaching services outside the mesh

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

An agentic application calls APIs that are not on the mesh: a source forge, a ticketing system, an internal REST service, a model provider. This guide puts a agentmesh-node in front of such a destination as a policy enforcement point. The application changes one base URL. The admin writes one policy document. The node decides every request on the method, the path and the caller, holds the credential the destination needs, and keeps it out of the application.

Headless enrollment

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

Servers, containers and routers cannot complete an interactive login: there is no browser, and no person to log in. Such a machine enrolls in one of two ways: with an OIDC token that it already holds, or with a bootstrap token that an operator mints for it. This guide covers both, and then explains what happens when the credential of such a node expires.

With an OIDC token that the workload already has

If the platform gives the workload a token from an issuer that the control plane trusts, no operator step is needed. Mark workload issuers with --workload-issuer on the control plane so workload tokens can enroll, refresh, and exchange credentials (POST /register, POST /refresh, POST /token/exchange), while being refused at human operator endpoints (/user/*, /oauth/authorize).

Kubernetes

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

This guide deploys a control plane, a router and a console into a cluster with the agentmesh-p2p Helm chart, then puts services on the mesh with the agentmesh-node chart. The last section lists the settings to change when you move from a test cluster to one that you keep. The public testnets run this setup on GKE. Their manifests are in .github/k8s/ in the repository.

What gets deployed

Component	Kind	Notes
`agentmesh-control-plane`	Deployment (2 replicas)	Stateless. All state is in PostgreSQL.
PostgreSQL	StatefulSet	In-cluster by default (`database.postgres.deployInternal`). You can point the chart at your own database instead.
`agentmesh-router`	StatefulSet	A PVC holds `router.key`, so the peer ID survives rescheduling.
`agentmesh-console`	Deployment	Optional (`console.enabled`).
bootstrap Job	Job (post-install hook)	Seeds the mesh policy and mints the router’s bootstrap token.
Gateway + HTTPRoute	Gateway API	Optional (`gateway.enabled`). Routes the enrollment paths and the console.

The chart does not include an identity provider, and the control plane needs one to start. The cluster’s own OIDC issuer is a good choice, because every pod can then enroll with a projected service account token and no secret has to be distributed.

Cloud Run

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

agentmesh-one serves its HTTP API, the web console, and the router’s WebSocket transport on a single port (8080), and ships as a pre-built container image (ghcr.io/google/agentmesh-one:latest). Because agentmesh-one automatically infers its public wss:// router address from Cloud Run’s Host and X-Forwarded-Proto headers on /info and /enroll and derives a deterministic router PeerID from AGENTMESH_ADMIN_TOKEN, you can deploy a standalone control plane and router to Google Cloud Run in a single command.

GitHub Codespaces

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

A codespace is a container that GitHub runs for you, with a terminal, an editor and an https URL for every port you forward. Started from this repository, it gives you a control plane of your own with nothing installed on your machine and no cloud account. agentmesh-one runs inside it, your laptop and your phone enroll over the public URL, and your GitHub account pays with its free Codespaces quota (120 core-hours a month on a Free plan; a 2-core machine is enough). The same setup lets you develop Agent Mesh, or a program that uses one of its SDKs, against a mesh that external clients can reach.

Native SDKs

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

An agent written in JavaScript or Python can be a member of the mesh itself, with no agentmesh-node beside it. The SDK enrolls with the control plane, joins through a router, finds services, calls MCP tools and inference or A2A endpoints, and answers A2A requests for the agent itself. Every caller of the agent is checked against the mesh policy before anything reaches your code.

This guide takes you from nothing to two programs on a mesh: an agent that other members can call, and a caller that reaches a service by name and the agent by its peer ID. Both programs are in the repository under sdk/js/examples and sdk/python/examples, and the repository’s tests run them against a real mesh, so what you read here is what runs.

SkyPilot

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

SkyPilot provisions and manages compute across Google Cloud, AWS, Azure, OCI, and Kubernetes using your existing cloud credentials (sky check). The repository includes a ready-to-run recipe, deploy/skypilot/agentmesh-one.yaml, that deploys a standalone agentmesh-one control plane and router with a persistent disk and an outbound Cloudflare HTTPS tunnel (requiring no inbound firewall rules).

(Note: While deploy/skypilot/agentmesh-one.yaml defaults to production VM sizing (cpus: 2+, memory: 8+, matching e2-standard-2 on GCP or t3.large on AWS), you can also set cpus: 0.25+ and memory: 1+ to run on cloud provider free tiers such as GCP e2-micro or AWS t4g.micro for testing.)