Guides on SAM

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 sam-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

sam-node reads sam-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 sam-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 sam-node run --daemonize:

The endpoint: http://127.0.0.1:8080/mcp (Streamable HTTP).
The token: the contents of ~/.config/sam-mesh/api-token, or the SAM_API_TOKEN you started the node with. It goes in the header X-Sam-Authentication: Bearer <token>.
The socket: ~/.config/sam-mesh/sam.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 sam-node is an HTTP server that they connect to. You can run sam-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.

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. On Kubernetes this is a projected service account token with the right audience:

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 sam-mesh Helm chart, then puts services on the mesh with the sam-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
`sam-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.
`sam-router`	StatefulSet	A PVC holds `router.key`, so the peer ID survives rescheduling.
`sam-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

sam-one serves its HTTP API, the console and the router’s WebSocket transport on one port. That is the shape Cloud Run expects. This guide deploys it there, joins nodes from anywhere, and lists what changes when sam-one runs on Cloud Run. The same steps apply to any platform that forwards HTTP and WebSockets to a container.

1. Build and push

PROJECT=my-project
REGION=us-central1
IMG=${REGION}-docker.pkg.dev/${PROJECT}/sam-mesh/sam-one:latest

docker build -f Dockerfile.sam-one -t "$IMG" .
gcloud auth configure-docker ${REGION}-docker.pkg.dev
docker push "$IMG"

2. Deploy

Cloud Run has no persistent disk, so the join and admin tokens are set through environment variables. Without this, a new instance would generate new tokens and nodes that enrolled earlier could not renew.