README
¶
Agent Mesh
Agent Mesh is a private network for AI agents. A node runs next to an agent and gives it three things: a way to publish tools and models to the network, a way to find and call what other nodes publish, and an identity every other node can verify. Nodes connect directly when they can and through relays when they cannot, so the network works across laptops, containers, clusters and phones behind NAT.
Note: We have updated the name to Agent Mesh to better align with the goals of the project in the ecosystem.
Two properties hold everywhere:
- Nothing is reachable by default. A node exposes no services until its configuration says so, and no node may call a service the mesh policy has not granted. Grants are evaluated on service names, never on addresses.
- Identity comes from your identity provider. A node enrolls with an OpenID Connect token or a one-time bootstrap token, and the control plane turns that into a short-lived, offline-verifiable credential bound to the node's own key.
Try it
curl -sL https://google.github.io/agentmesh/install.sh | bash # agentmesh-node, mcp-client and friends
agentmesh-node join https://bananas.sam-mesh.dev # one-time login
agentmesh-node run --daemonize # local MCP server on 127.0.0.1:8080
agentmesh-node skill install # teach your agent to use it
Your agent now has tools that discover and call services across the mesh,
and an OpenAI-compatible endpoint that routes model requests to whoever
serves the model. bananas.sam-mesh.dev is a shared developer testnet with
no uptime promise; the quick start
walks through it, and your own mesh
runs a control plane on your laptop in one command.
To run a control plane of your own without installing anything, open a
GitHub codespace with the released binaries and run make testnet. It
starts on a public https URL that your laptop and phone can enroll into,
on your GitHub account's free quota:
The Codespaces guide has the steps, what persists and what stops.
What is in a mesh
| Program | Role |
|---|---|
agentmesh-control-plane |
Verifies who is joining, issues each node a signed credential, and holds the policy that says who may call what. |
agentmesh-router |
A well-known peer that nodes connect to first. Relays traffic between nodes that cannot reach each other and hosts the discovery table. |
agentmesh-node |
Runs next to your agent or service. Enrolls, connects, serves your local backends to the mesh, and exposes the mesh to your agent as a local MCP server and OpenAI-compatible API. |
agentmesh-one |
The control plane, a router and a web console in one binary, for laptops and small deployments. |
Documentation
google.github.io/agentmesh/docs is built from site/.
- Getting started: one node on the testnet, then a mesh of your own.
- Concepts: architecture, identity and enrollment, authorization, networking.
- Guides: exposing services, connecting agent clients, headless enrollment, Kubernetes, Cloud Run.
- Reference: every flag, configuration key, HTTP route and policy field.
- Preview: sandboxed agents and the mobile app, which work but are still settling.
- Contributing: building, testing and the local kind environment.
The repository has a dev container with the Go, Node and Python toolchains and Docker, so you can build and test in a codespace or in VS Code without installing anything:
Status
Agent Mesh is pre-1.0. The node, routers, control plane, identity and policy model are stable in shape and exercised by the test suite and two public testnets; see ROADMAP.md for the release plan. Sandboxed agent blueprints and the mobile app are in preview.
License and disclaimer
Apache-2.0; see LICENSE. This is not an officially supported Google product, and it is not eligible for the Google Open Source Software Vulnerability Rewards Program.
Directories
¶
| Path | Synopsis |
|---|---|
|
agents
|
|
|
skills/agentmesh
Package agentmeshskill embeds the Agent Mesh agent skill document so it ships inside the binaries that install it.
|
Package agentmeshskill embeds the Agent Mesh agent skill document so it ships inside the binaries that install it. |
|
cmd
|
|
|
agentmesh-bench
command
Command agentmesh-bench measures what an agent experiences when it reaches the mesh through a sandbox boundary.
|
Command agentmesh-bench measures what an agent experiences when it reaches the mesh through a sandbox boundary. |
|
agentmesh-console
command
|
|
|
agentmesh-control-plane
command
|
|
|
agentmesh-node
command
|
|
|
agentmesh-one
command
agentmesh-one is the all-in-one Agent Mesh distribution: control plane, libp2p router and storage in a single binary serving a single public port.
|
agentmesh-one is the all-in-one Agent Mesh distribution: control plane, libp2p router and storage in a single binary serving a single public port. |
|
agentmesh-router
command
|
|
|
mcp-client
command
|
|
|
development
|
|
|
examples/code-reviewer-pool/samples
Sample file with intentional issues for the reviewer pool to find.
|
Sample file with intentional issues for the reviewer pool to find. |
|
hack
|
|
|
gen-sdk-datalog
command
Command gen-sdk-datalog writes the baseline Datalog a mesh member evaluates when it authorizes a caller, as api/datalog.go and api/tar.go define it, into the JSON/TS artifacts the native SDKs embed, and generates the deterministic cross-language TAR conformance vectors in sdk/testdata/tar_conformance.json.
|
Command gen-sdk-datalog writes the baseline Datalog a mesh member evaluates when it authorizes a caller, as api/datalog.go and api/tar.go define it, into the JSON/TS artifacts the native SDKs embed, and generates the deterministic cross-language TAR conformance vectors in sdk/testdata/tar_conformance.json. |
|
gen-sdk-docs
command
Command gen-sdk-docs copies the SDK example programs into the Markdown that shows them, so what the READMEs and the guide print is the file CI compiles and runs against a mesh.
|
Command gen-sdk-docs copies the SDK example programs into the Markdown that shows them, so what the READMEs and the guide print is the file CI compiles and runs against a mesh. |
|
internal
|
|
|
bench
Package bench drives a reproducible agent workload against the mesh.
|
Package bench drives a reproducible agent workload against the mesh. |
|
controlplane/client
Package client is how a mesh component reads from its control plane.
|
Package client is how a mesh component reads from its control plane. |
|
credprovider
Package credprovider implements outbound credential brokering for Agent Mesh egress destinations (static secrets, RFC 8693 OIDC federation with optional Google Service Account impersonation, AWS STS AssumeRoleWithWebIdentity with inline IAM session policy compilation, and platform metadata identity) as well as TaskAuthorizationRule scope/permission/resource narrowing.
|
Package credprovider implements outbound credential brokering for Agent Mesh egress destinations (static secrets, RFC 8693 OIDC federation with optional Google Service Account impersonation, AWS STS AssumeRoleWithWebIdentity with inline IAM session policy compilation, and platform metadata identity) as well as TaskAuthorizationRule scope/permission/resource narrowing. |
|
envoy
Package envoy implements Envoy ext_authz (HTTP and gRPC v3/v2) and ext_proc (gRPC v3 gateway server and outbound inspection callout client) using official google.golang.org/grpc and envoyproxy/go-control-plane bindings.
|
Package envoy implements Envoy ext_authz (HTTP and gRPC v3/v2) and ext_proc (gRPC v3 gateway server and outbound inspection callout client) using official google.golang.org/grpc and envoyproxy/go-control-plane bindings. |
|
logging
Package logging configures go-log the same way in every binary.
|
Package logging configures go-log the same way in every binary. |
|
p2plimits
Package p2plimits builds the libp2p resource manager a mesh component runs with: limits sized from its connection budget, a per-source-address connection cap and rate in place of libp2p's default of 8, applied to the address a connection comes from and not to a relay it comes through, and a wrapper that counts and logs every inbound connection the manager refuses.
|
Package p2plimits builds the libp2p resource manager a mesh component runs with: limits sized from its connection budget, a per-source-address connection cap and rate in place of libp2p's default of 8, applied to the address a connection comes from and not to a relay it comes through, and a wrapper that counts and logs every inbound connection the manager refuses. |
|
pprofserver
Package pprofserver serves Go's runtime profiles on a listener of their own.
|
Package pprofserver serves Go's runtime profiles on a listener of their own. |
|
ratelimit
Package ratelimit bounds how often an individual peer may make a node or router do pre-authentication work.
|
Package ratelimit bounds how often an individual peer may make a node or router do pre-authentication work. |
|
secrets
Package secrets resolves secret configuration for Agent Mesh binaries.
|
Package secrets resolves secret configuration for Agent Mesh binaries. |
|
skill
Package skill installs the Agent Mesh agent skill into the directories local AI agents scan, so an agent can bootstrap a node and drive the mesh without the user pasting instructions by hand.
|
Package skill installs the Agent Mesh agent skill into the directories local AI agents scan, so an agent can bootstrap a node and drive the mesh without the user pasting instructions by hand. |
|
standalone
Package standalone wires the control plane, the libp2p router and the shared SQL store into one process serving a single public port: the router's WebSocket listener carries libp2p upgrades while every other HTTP request falls through to the control-plane mux.
|
Package standalone wires the control plane, the libp2p router and the shared SQL store into one process serving a single public port: the router's WebSocket listener carries libp2p upgrades while every other HTTP request falls through to the control-plane mux. |
|
tlsinspect
Package tlsinspect parses and verifies TLS ClientHello records on named TCP tunnels without terminating TLS.
|
Package tlsinspect parses and verifies TLS ClientHello records on named TCP tunnels without terminating TLS. |
|
tunnel
Package tunnel publishes a local HTTP listener on a public https URL through a third-party connector, so devices that cannot route to the host (a phone on cellular, a laptop on another network) can still enroll and join the mesh.
|
Package tunnel publishes a local HTTP listener on a public https URL through a third-party connector, so devices that cannot route to the host (a phone on cellular, a laptop on another network) can still enroll and join the mesh. |
|
mobile
|
|
|
agentmesh-node-ffi
command
|
|
|
tests
|
|
|
e2e
command
|
|
|
scale/stdio-mcp
command
Command stdio-mcp is an MCP server over stdio, for a provider node in a local mesh.
|
Command stdio-mcp is an MCP server over stdio, for a provider node in a local mesh. |
Click to show internal directories.
Click to hide internal directories.