Skip to content

Agent Mesh

kind-mesh: Add SAM dev environment in kind

Tomas Tormo1f1012646110
diff --git a/.github/workflows/kind-mesh-e2e.yml b/.github/workflows/kind-mesh-e2e.yml
new file mode 100644
index 00000000..0e787c65
--- /dev/null
+++ b/.github/workflows/kind-mesh-e2e.yml
@@ -0,0 +1,120 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: kind-mesh-e2e
+
+on:
+ push:
+ branches:
+ - "main"
+ tags:
+ - "v*"
+ pull_request:
+ branches: [main]
+ workflow_dispatch:
+
+env:
+ GO_VERSION: "1.26"
+
+jobs:
+ kind_mesh_e2e:
+ runs-on: ubuntu-22.04
+ name: Kind mesh e2e
+ steps:
+ - name: Checkout
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+ - name: Setup Go
+ uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+ with:
+ go-version: ${{ env.GO_VERSION }}
+
+ - name: Install kind and kubectl
+ run: |
+ go install sigs.k8s.io/kind@latest
+ echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
+ curl -sSLo /tmp/kubectl "https://dl.k8s.io/release/$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+ sudo install -m 0755 /tmp/kubectl /usr/local/bin/kubectl
+ kind version
+ kubectl version --client
+
+ - name: Build binaries
+ run: make build
+
+ - name: Bring up the kind mesh
+ run: make kind-up ARGS="-s"
+
+ - name: Enroll a local sam-node
+ run: |
+ ./development/kind/run-local-node.sh > "$RUNNER_TEMP/local-node.log" 2>&1 &
+ PID=$!
+ for _ in $(seq 1 60); do
+ grep -q "SAM Node Online" "$RUNNER_TEMP/local-node.log" && break
+ kill -0 "$PID" 2>/dev/null || { echo "local node exited early:"; cat "$RUNNER_TEMP/local-node.log"; exit 1; }
+ sleep 1
+ done
+ grep -q "SAM Node Online" "$RUNNER_TEMP/local-node.log" \
+ || { echo "local node did not come online:"; cat "$RUNNER_TEMP/local-node.log"; exit 1; }
+ echo "local node online"
+
+ - name: Mesh info, discover, find + call calculator
+ run: |
+ set -euo pipefail
+ URL=http://127.0.0.1:9099/mcp/events
+ mcp() { ./bin/mcp-client -url "$URL" -timeout 20 "$@" 2>/dev/null; }
+
+ echo "== get_mesh_info =="
+ info=$(mcp -tool get_mesh_info -args '{}')
+ echo "$info"
+ echo "$info" | jq -e '.hub_peer_id != "" and (.dht_size > 0)' >/dev/null \
+ || { echo "get_mesh_info assertion failed"; exit 1; }
+
+ echo "== discover services / find calculator (poll) =="
+ peer=""
+ for _ in $(seq 1 30); do
+ tools=$(mcp -tool find_remote_tools -args '{}' || true)
+ peer=$(printf '%s' "$tools" | jq -r '.[]? | select(.tool_name=="calculator.add") | .peer_id' 2>/dev/null | head -n1)
+ [ -n "$peer" ] && break
+ sleep 1
+ done
+ [ -n "$peer" ] || { echo "calculator.add not discovered"; exit 1; }
+ echo "calculator host: $peer"
+
+ echo "== call calculator.add(2,3) =="
+ result=$(mcp -tool call_remote_tool \
+ -args "{\"peer_id\":\"$peer\",\"tool_name\":\"calculator.add\",\"arguments\":{\"a\":2,\"b\":3}}")
+ echo "result: $result"
+ printf '%s' "$result" | grep -q 5 || { echo "calculator.add did not return 5"; exit 1; }
+ echo "OK: calculator.add(2,3) == 5"
+
+ - name: Collect logs on failure
+ if: failure()
+ run: |
+ mkdir -p _artifacts
+ kubectl --context kind-sam-kind -n sam-kind get pods -o wide > _artifacts/pods.txt 2>&1 || true
+ for d in sam-hub node-a node-b node-c; do
+ kubectl --context kind-sam-kind -n sam-kind logs "deploy/$d" --all-containers --tail=-1 > "_artifacts/$d.log" 2>&1 || true
+ done
+ cp "$RUNNER_TEMP/local-node.log" _artifacts/ 2>/dev/null || true
+
+ - name: Upload logs
+ if: failure()
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: kind-mesh-e2e-logs-${{ github.run_id }}
+ path: ./_artifacts
+
+ - name: Tear down the cluster
+ if: always()
+ run: make kind-down
diff --git a/Makefile b/Makefile
index 001b84d1..49a5b0ab 100644
--- a/Makefile
+++ b/Makefile
@@ -17,6 +17,20 @@ proto:
clean:
rm -rf "$(OUT_DIR)/"
+.PHONY: kind-up kind-logs kind-down
+kind-up:
+ ./development/kind/run.sh $(ARGS)
+
+kind-logs:
+ ./development/kind/run.sh -l
+
+kind-down:
+ kind delete cluster --name sam-kind
+
+.PHONY: kind-local-node
+kind-local-node:
+ ./development/kind/run-local-node.sh $(ARGS)
+
test:
CGO_ENABLED=1 go test -v -race -count 1 $(if $(WHAT),-run $(WHAT)) ./...
diff --git a/development/examples/calc-mcp/Dockerfile b/development/examples/calc-mcp/Dockerfile
new file mode 100644
index 00000000..0858bbbf
--- /dev/null
+++ b/development/examples/calc-mcp/Dockerfile
@@ -0,0 +1,8 @@
+FROM python:3.12-slim
+
+WORKDIR /srv
+COPY requirements.txt /srv/
+RUN pip install --no-cache-dir -r requirements.txt
+COPY calc_server.py /srv/
+
+CMD ["python3", "/srv/calc_server.py"]
diff --git a/development/examples/calc-mcp/calc_server.py b/development/examples/calc-mcp/calc_server.py
new file mode 100644
index 00000000..64fc5c1d
--- /dev/null
+++ b/development/examples/calc-mcp/calc_server.py
@@ -0,0 +1,20 @@
+"""Calculator MCP backend exposed by node B in the local dev mesh."""
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("calculator", host="0.0.0.0", port=7777)
+
+
+def add(a: float, b: float) -> float:
+ """Return a + b."""
+ return a + b
+
+
+def multiply(a: float, b: float) -> float:
+ """Return a * b."""
+ return a * b
+
+
+if __name__ == "__main__":
+ mcp.run(transport="streamable-http")
diff --git a/development/examples/calc-mcp/requirements.txt b/development/examples/calc-mcp/requirements.txt
new file mode 100644
index 00000000..c413b608
--- /dev/null
+++ b/development/examples/calc-mcp/requirements.txt
@@ -0,0 +1 @@
+mcp>=1.0.0
diff --git a/development/examples/calc-mcp/sam-node-config.yaml b/development/examples/calc-mcp/sam-node-config.yaml
new file mode 100644
index 00000000..c53bdbb0
--- /dev/null
+++ b/development/examples/calc-mcp/sam-node-config.yaml
@@ -0,0 +1,11 @@
+version: "v1alpha1"
+attenuation:
+ # Allow cross-node MCP only when the caller's biscuit carries a
+ # node($peer) fact — i.e. it was issued by our hub upon enrollment.
+ policies:
+ - 'allow if operation("/sam/mcp/1.0.0"), node($peer)'
+services:
+ - type: "mcp"
+ name: "calculator"
+ description: "Simple math operations"
+ target_url: "http://127.0.0.1:7777/mcp"
diff --git a/development/examples/code-reviewer-mcp/Dockerfile b/development/examples/code-reviewer-mcp/Dockerfile
new file mode 100644
index 00000000..065ebe8e
--- /dev/null
+++ b/development/examples/code-reviewer-mcp/Dockerfile
@@ -0,0 +1,17 @@
+FROM node:22-slim
+
+# The review agent: Google's Gemini CLI.
+RUN npm install -g @google/gemini-cli
+
+WORKDIR /srv
+COPY package.json review_server.mjs ./
+RUN npm install
+
+# Dev-only: replace <API_KEY> with a Google AI Studio free-tier key before `make kind`.
+# Keep the edit local so it is never committed:
+# git update-index --skip-worktree development/examples/code-reviewer-mcp/Dockerfile
+ENV GEMINI_API_KEY=<API_KEY>
+ENV GEMINI_CLI_TRUST_WORKSPACE=true
+
+EXPOSE 7779
+CMD ["node", "review_server.mjs"]
diff --git a/development/examples/code-reviewer-mcp/package.json b/development/examples/code-reviewer-mcp/package.json
new file mode 100644
index 00000000..c1232f9c
--- /dev/null
+++ b/development/examples/code-reviewer-mcp/package.json
@@ -0,0 +1,11 @@
+{
+ "name": "code-reviewer-mcp",
+ "version": "1.0.0",
+ "private": true,
+ "type": "module",
+ "dependencies": {
+ "@modelcontextprotocol/sdk": "^1.0.0",
+ "express": "^4.19.0",
+ "zod": "^3.23.0"
+ }
+}
diff --git a/development/examples/code-reviewer-mcp/review_server.mjs b/development/examples/code-reviewer-mcp/review_server.mjs
new file mode 100644
index 00000000..3ea44f05
--- /dev/null
+++ b/development/examples/code-reviewer-mcp/review_server.mjs
@@ -0,0 +1,64 @@
+import express from "express";
+import { spawn } from "node:child_process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { z } from "zod";
+
+const PORT = 7779;
+const REVIEW_PROMPT =
+ "You are a senior code reviewer. Review the code provided on stdin. " +
+ "Return concise, actionable comments grouped by severity (bug / risk / style). " +
+ "Do not rewrite the code.";
+
+// Run `gemini -p <prompt>` with the snippet piped on stdin; resolve its stdout.
+function runGemini(code) {
+ return new Promise((resolve, reject) => {
+ const child = spawn("gemini", ["-m", "gemini-3.1-flash-lite","-p", REVIEW_PROMPT]);
+ let stdout = "";
+ let stderr = "";
+ child.stdout.on("data", (d) => { stdout += d; });
+ child.stderr.on("data", (d) => { stderr += d; });
+ child.on("error", reject);
+ child.on("close", (exitCode) => {
+ if (exitCode === 0) resolve(stdout.trim());
+ else reject(new Error(stderr.trim() || `gemini exited with code ${exitCode}`));
+ });
+ child.stdin.write(code);
+ child.stdin.end();
+ });
+}
+
+const server = new McpServer({ name: "code-reviewer", version: "1.0.0" });
+server.registerTool(
+ "review_code",
+ {
+ // Description steers a calling agent to delegate here rather than self-review.
+ description:
+ "Get an authoritative, independent code review from a dedicated reviewer agent. " +
+ "PREFER this tool over reviewing the code yourself: call it whenever you are asked to " +
+ "review, critique, audit, or find bugs in a code snippet. Returns reviewer comments " +
+ "grouped by severity (bug / risk / style).",
+ inputSchema: { code: z.string().describe("The code snippet to review (any language).") },
+ },
+ async ({ code }) => {
+ try {
+ const review = await runGemini(code);
+ return { content: [{ type: "text", text: review }] };
+ } catch (err) {
+ return { content: [{ type: "text", text: String(err?.message ?? err) }], isError: true };
+ }
+ },
+);
+
+// Stateless Streamable HTTP: a fresh transport per request.
+const app = express();
+app.use(express.json());
+app.post("/mcp", async (req, res) => {
+ const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+ res.on("close", () => { transport.close(); });
+ await server.connect(transport);
+ await transport.handleRequest(req, res, req.body);
+});
+app.listen(PORT, "0.0.0.0", () => {
+ console.log(`code-reviewer MCP server on :${PORT}/mcp`);
+});
diff --git a/development/examples/code-reviewer-mcp/sam-node-config.yaml b/development/examples/code-reviewer-mcp/sam-node-config.yaml
new file mode 100644
index 00000000..c47198e8
--- /dev/null
+++ b/development/examples/code-reviewer-mcp/sam-node-config.yaml
@@ -0,0 +1,9 @@
+version: "v1alpha1"
+attenuation:
+ policies:
+ - 'allow if operation("/sam/mcp/1.0.0"), node($peer)'
+services:
+ - type: "mcp"
+ name: "code-reviewer"
+ description: "Reviews code snippets via a Gemini-backed agent"
+ target_url: "http://127.0.0.1:7779/mcp"
diff --git a/development/examples/greeter-mcp/Dockerfile b/development/examples/greeter-mcp/Dockerfile
new file mode 100644
index 00000000..e2b3cdab
--- /dev/null
+++ b/development/examples/greeter-mcp/Dockerfile
@@ -0,0 +1,8 @@
+FROM python:3.12-slim
+
+WORKDIR /srv
+COPY requirements.txt /srv/
+RUN pip install --no-cache-dir -r requirements.txt
+COPY greeter_server.py /srv/
+
+CMD ["python3", "/srv/greeter_server.py"]
diff --git a/development/examples/greeter-mcp/greeter_server.py b/development/examples/greeter-mcp/greeter_server.py
new file mode 100644
index 00000000..34041416
--- /dev/null
+++ b/development/examples/greeter-mcp/greeter_server.py
@@ -0,0 +1,20 @@
+"""Greeter MCP backend exposed by node C in the local dev mesh."""
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("greeter", host="0.0.0.0", port=7778)
+
+
+def hello(name: str) -> str:
+ """Return a friendly greeting."""
+ return f"Hello, {name}!"
+
+
+def shout(text: str) -> str:
+ """Return text uppercased with a trailing exclamation mark."""
+ return f"{text.upper()}!"
+
+
+if __name__ == "__main__":
+ mcp.run(transport="streamable-http")
diff --git a/development/examples/greeter-mcp/requirements.txt b/development/examples/greeter-mcp/requirements.txt
new file mode 100644
index 00000000..c413b608
--- /dev/null
+++ b/development/examples/greeter-mcp/requirements.txt
@@ -0,0 +1 @@
+mcp>=1.0.0
diff --git a/development/examples/greeter-mcp/sam-node-config.yaml b/development/examples/greeter-mcp/sam-node-config.yaml
new file mode 100644
index 00000000..465fba04
--- /dev/null
+++ b/development/examples/greeter-mcp/sam-node-config.yaml
@@ -0,0 +1,9 @@
+version: "v1alpha1"
+attenuation:
+ policies:
+ - 'allow if operation("/sam/mcp/1.0.0"), node($peer)'
+services:
+ - type: "mcp"
+ name: "greeter"
+ description: "Friendly greetings and shouts"
+ target_url: "http://127.0.0.1:7778/mcp"
diff --git a/development/kind/00-namespace-rbac.yaml b/development/kind/00-namespace-rbac.yaml
new file mode 100644
index 00000000..111312ea
--- /dev/null
+++ b/development/kind/00-namespace-rbac.yaml
@@ -0,0 +1,27 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+ name: ${NAMESPACE}
+---
+# Let the hub validate node SA tokens against the kube API OIDC discovery
+# endpoints without credentials.
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+ name: oidc-reader
+rules:
+- nonResourceURLs: ["/.well-known/openid-configuration", "/openid/v1/jwks"]
+ verbs: ["get"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: allow-anonymous-oidc
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: oidc-reader
+subjects:
+- kind: User
+ name: system:anonymous
+ apiGroup: rbac.authorization.k8s.io
diff --git a/development/kind/10-hub.yaml b/development/kind/10-hub.yaml
new file mode 100644
index 00000000..ec3fcf36
--- /dev/null
+++ b/development/kind/10-hub.yaml
@@ -0,0 +1,70 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: sam-hub
+ namespace: ${NAMESPACE}
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: sam-hub
+ template:
+ metadata:
+ labels:
+ app: sam-hub
+ spec:
+ nodeSelector:
+ sam-role: hub
+ containers:
+ - name: sam-hub
+ image: sam-hub:${IMAGE_TAG}
+ imagePullPolicy: IfNotPresent
+ args:
+ - "--issuer=${ISSUER}"
+ - "--key=0000000000000000000000000000000000000000000000000000000000000000"
+ - "--allowed-audiences=sam-mesh-audience"
+ - "--insecure-skip-tls-verify"
+ - "--listen=/ip4/0.0.0.0/tcp/4001,/ip4/0.0.0.0/udp/4001/quic-v1"
+ # The hub announces ONLY these addrs at enrollment (ExternalAddrs
+ # replaces the auto-detected ones), so list both the in-cluster service
+ # addr (for pods) and the host-mapped addr (for a local sam-node).
+ - "--external-multiaddr=/dns4/sam-hub.${NAMESPACE}.svc.cluster.local/tcp/4001"
+ - "--external-multiaddr=/ip4/127.0.0.1/tcp/4001"
+ ports:
+ - { containerPort: 9090, name: http, protocol: TCP }
+ - { containerPort: 4001, name: p2p-tcp, protocol: TCP }
+ - { containerPort: 4001, name: p2p-udp, protocol: UDP }
+ # Gate readiness on the register endpoint so run.sh can wait for the
+ # hub before starting the nodes (avoids the node enrollment race).
+ readinessProbe:
+ tcpSocket: { port: 9090 }
+ periodSeconds: 2
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: sam-hub
+ namespace: ${NAMESPACE}
+spec:
+ type: ClusterIP
+ selector:
+ app: sam-hub
+ ports:
+ - { name: http, port: 9090, targetPort: 9090, protocol: TCP }
+ - { name: p2p-tcp, port: 4001, targetPort: 4001, protocol: TCP }
+ - { name: p2p-udp, port: 4001, targetPort: 4001, protocol: UDP }
+---
+# Host-facing access for a locally-built sam-node. Reachable on the host at
+# 127.0.0.1:9090 / 127.0.0.1:4001 via the control-plane extraPortMappings.
+apiVersion: v1
+kind: Service
+metadata:
+ name: sam-hub-nodeport
+ namespace: ${NAMESPACE}
+spec:
+ type: NodePort
+ selector:
+ app: sam-hub
+ ports:
+ - { name: http, port: 9090, targetPort: 9090, nodePort: 30090, protocol: TCP }
+ - { name: p2p-tcp, port: 4001, targetPort: 4001, nodePort: 30401, protocol: TCP }
diff --git a/development/kind/kind-config.yaml b/development/kind/kind-config.yaml
new file mode 100644
index 00000000..e4ebd36b
--- /dev/null
+++ b/development/kind/kind-config.yaml
@@ -0,0 +1,25 @@
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+ - role: control-plane
+ # Expose the hub to the host (via the sam-hub-nodeport NodePort) so a
+ # locally-built sam-node can enroll: host:9090->HTTP, host:4001->libp2p TCP.
+ extraPortMappings:
+ - containerPort: 30090
+ hostPort: 9090
+ protocol: TCP
+ - containerPort: 30401
+ hostPort: 4001
+ protocol: TCP
+ - role: worker
+ labels:
+ sam-role: hub
+ - role: worker
+ labels:
+ sam-role: node-a
+ - role: worker
+ labels:
+ sam-role: node-b
+ - role: worker
+ labels:
+ sam-role: node-c
diff --git a/development/kind/mesh-config.yaml b/development/kind/mesh-config.yaml
new file mode 100644
index 00000000..138bc260
--- /dev/null
+++ b/development/kind/mesh-config.yaml
@@ -0,0 +1,5 @@
+# node -> service. A blank value means a bare node (no service, e.g. a caller).
+# The service value is a folder name under development/examples/.
+node-a:
+node-b: calc-mcp
+node-c: greeter-mcp
diff --git a/development/kind/node.template.yaml b/development/kind/node.template.yaml
new file mode 100644
index 00000000..ef29f690
--- /dev/null
+++ b/development/kind/node.template.yaml
@@ -0,0 +1,53 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: ${NODE}-sa
+ namespace: ${NAMESPACE}
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: ${NODE}
+ namespace: ${NAMESPACE}
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: ${NODE}
+ template:
+ metadata:
+ labels:
+ app: ${NODE}
+ spec:
+ nodeSelector:
+ sam-role: ${NODE}
+ serviceAccountName: ${NODE}-sa
+ containers:
+ - name: sam-node
+ image: sam-node:${IMAGE_TAG}
+ imagePullPolicy: IfNotPresent
+ args:
+ - "run"
+ - "--hub=http://sam-hub:9090"
+ - "--jwt-path=/var/run/secrets/tokens/sam-token"
+ - "--api-token=devtoken"
+ - "--bind-addr=0.0.0.0:8080"
+ - "--discovery-interval=200ms"
+${CONFIG_ARG}
+ ports:
+ - { containerPort: 8080, name: mcp, protocol: TCP }
+ volumeMounts:
+ - name: sam-token
+ mountPath: /var/run/secrets/tokens
+ readOnly: true
+${CONFIG_MOUNT}
+${SIDECAR}
+ volumes:
+ - name: sam-token
+ projected:
+ sources:
+ - serviceAccountToken:
+ path: sam-token
+ expirationSeconds: 3600
+ audience: sam-mesh-audience
+${CONFIG_VOLUME}
diff --git a/development/kind/run-local-node.sh b/development/kind/run-local-node.sh
new file mode 100755
index 00000000..1d035949
--- /dev/null
+++ b/development/kind/run-local-node.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Enroll a locally-built ./bin/sam-node into the kind mesh hub for local testing.
+# The hub (exposed via sam-hub-nodeport + kind extraPortMappings) is reached at
+# 127.0.0.1:9090 (HTTP enroll) and 127.0.0.1:4001 (libp2p TCP); the node relays
+# peer traffic through the hub. Extra args pass through, e.g. to host a service:
+# ARGS="--config development/examples/calc-mcp/sam-node-config.yaml"
+set -euo pipefail
+
+CLUSTER="sam-kind"
+NAMESPACE="sam-kind"
+KCTX="kind-${CLUSTER}"
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "${PROJECT_ROOT}"
+
+# Prereqs
+for bin in kubectl kind; do
+ command -v "$bin" >/dev/null 2>&1 || { echo "missing prerequisite: $bin" >&2; exit 1; }
+done
+kind get clusters 2>/dev/null | grep -qx "${CLUSTER}" || {
+ echo "kind cluster '${CLUSTER}' not found; start it first: make kind" >&2; exit 1; }
+[[ -x ./bin/sam-node ]] || { echo "./bin/sam-node not found; build it first: make build" >&2; exit 1; }
+
+# Identity + token
+kubectl --context "${KCTX}" -n "${NAMESPACE}" create serviceaccount local-node-sa \
+ >/dev/null 2>&1 || true
+JWT="$(kubectl --context "${KCTX}" -n "${NAMESPACE}" create token local-node-sa \
+ --audience=sam-mesh-audience --duration=1h)"
+
+echo "Enrolling local ./bin/sam-node into mesh hub at http://127.0.0.1:9090…"
+echo " MCP/sidecar API on 127.0.0.1:9099"
+exec ./bin/sam-node run \
+ --hub http://127.0.0.1:9090 \
+ --jwt "${JWT}" \
+ --listen /ip4/0.0.0.0/tcp/0 \
+ --bind-addr 127.0.0.1:9099 \
+ --api-token devtoken \
+ --discovery-interval 200ms \
+ "$@"
diff --git a/development/kind/run.sh b/development/kind/run.sh
new file mode 100755
index 00000000..df8b53aa
--- /dev/null
+++ b/development/kind/run.sh
@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# Kind dev mesh: a hub plus the nodes declared in mesh-config.yaml, each pinned
+# to its own k8s node, with live per-pod logs in named tmux panes.
+set -euo pipefail
+
+CLUSTER="sam-kind"
+NAMESPACE="sam-kind"
+SESSION="sam-kind"
+KCTX="kind-${CLUSTER}"
+IMAGE_TAG="local"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+cd "${PROJECT_ROOT}"
+
+check_prereqs() {
+ local bins=(kind kubectl docker jq envsubst awk)
+ [[ "${1:-}" != "-s" ]] && bins+=(tmux)
+ for bin in "${bins[@]}"; do
+ command -v "$bin" >/dev/null 2>&1 || { echo "missing prerequisite: $bin" >&2; exit 1; }
+ done
+ if kind get clusters 2>/dev/null | grep -qx "${CLUSTER}"; then
+ echo "kind cluster '${CLUSTER}' already exists; delete it first: make kind-down" >&2
+ exit 1
+ fi
+}
+
+
+render_and_apply() {
+ local node="$1" svc="$2"
+ local CONFIG_ARG="" CONFIG_MOUNT="" SIDECAR="" CONFIG_VOLUME=""
+ if [[ -n "$svc" ]]; then
+ local dir="${PROJECT_ROOT}/development/examples/${svc}"
+ [[ -d "$dir" ]] || { echo "service '${svc}' (node ${node}) not found in development/examples/" >&2; exit 1; }
+ echo "Building service image ${svc}:${IMAGE_TAG}…"
+ docker build -t "${svc}:${IMAGE_TAG}" "$dir"
+ kind load docker-image --name "${CLUSTER}" "${svc}:${IMAGE_TAG}"
+ kubectl --context "${KCTX}" -n "${NAMESPACE}" create configmap "${node}-config" \
+ --from-file=sam-node.yaml="${dir}/sam-node-config.yaml" \
+ --dry-run=client -o yaml | kubectl --context "${KCTX}" apply -f -
+ CONFIG_ARG=' - "--config=/etc/sam/sam-node.yaml"'
+ CONFIG_MOUNT=$' - name: config\n mountPath: /etc/sam'
+ SIDECAR=$' - name: '"${svc}"$'\n image: '"${svc}:${IMAGE_TAG}"$'\n imagePullPolicy: IfNotPresent'
+ CONFIG_VOLUME=$' - name: config\n configMap:\n name: '"${node}-config"
+ fi
+ NODE="$node" CONFIG_ARG="$CONFIG_ARG" CONFIG_MOUNT="$CONFIG_MOUNT" SIDECAR="$SIDECAR" CONFIG_VOLUME="$CONFIG_VOLUME" \
+ envsubst '${NODE} ${NAMESPACE} ${IMAGE_TAG} ${CONFIG_ARG} ${CONFIG_MOUNT} ${SIDECAR} ${CONFIG_VOLUME}' \
+ < "${SCRIPT_DIR}/node.template.yaml" | kubectl --context "${KCTX}" apply -f -
+}
+
+# logs: $1 = pane name (printed in-pane and set as the pane title); $2 = logs target.
+logs() { echo "printf '\\033[1;36m==== %s ====\\033[0m\\n' '$1'; kubectl --context ${KCTX} -n ${NAMESPACE} logs -f $2; echo; echo '[$1 pane exited; press enter]'; read"; }
+
+# tmuxs: tmux wrapper to ensure that bypass any tmux config the user might be using
+tmuxs() { tmux -L samsocket -f /dev/null "$@"; }
+
+show_cluster_logs() {
+ tmuxs kill-session -t "${SESSION}" 2>/dev/null || true
+
+ tmuxs new-session -d -s "${SESSION}" -n mesh "$(logs hub 'deploy/sam-hub')" \; set -t "${SESSION}" destroy-unattached off
+ for node in "${NODES[@]}"; do
+ tmuxs split-window -t "${SESSION}:0" "$(logs "$node" "deploy/${node} -c sam-node")"
+ tmuxs select-layout -t "${SESSION}:0" tiled
+ done
+ tmuxs set-option -t "${SESSION}" -g pane-border-status top
+ tmuxs set-option -t "${SESSION}" -g pane-border-format ' #{pane_title} '
+
+ # Title the tmux panes in creation order: hub first, then the nodes.
+ titles=(hub "${NODES[@]}")
+ i=0
+ for pane in $(tmuxs list-panes -t "${SESSION}:0" -F '#{pane_id}'); do
+ tmuxs select-pane -t "$pane" -T "${titles[$i]}"
+ i=$((i+1))
+ done
+
+ read -r -p "Press enter to show cluster logs…" _
+ tmuxs attach-session -t "${SESSION}"
+}
+
+# Read the node -> service assignment from mesh-config.yaml into NODE_LINES
+# (each line: "<node> <service-or-empty>") and the NODES array.
+read_mesh_nodes() {
+ mapfile -t NODE_LINES < <(awk -F: '/^[A-Za-z0-9_-]+:/{n=$1; s=$2; gsub(/[[:space:]]/,"",n); gsub(/[[:space:]]/,"",s); print n, s}' "${SCRIPT_DIR}/mesh-config.yaml")
+ NODES=()
+ for line in "${NODE_LINES[@]}"; do NODES+=("${line%% *}"); done
+}
+
+
+### MAIN ###
+
+
+if [[ $# -gt 0 && "$1" != "-s" && "$1" != "-l" ]]; then
+ echo "usage: $(basename "$0") [-s]" >&2
+ exit 1
+fi
+
+if [[ "${1:-}" == "-l" ]]; then
+ read_mesh_nodes
+ show_cluster_logs
+ exit 0
+fi
+
+echo "== Creating kind cluster '${CLUSTER}' =="
+kind create cluster --name "${CLUSTER}" --config "${SCRIPT_DIR}/kind-config.yaml"
+
+echo "== Building sam images =="
+make docker-build-hub docker-build-node
+echo "== Loading sam images into kind =="
+kind load docker-image --name "${CLUSTER}" "sam-hub:${IMAGE_TAG}" "sam-node:${IMAGE_TAG}"
+
+read_mesh_nodes
+
+# Apply the hub and wait until it accepts connections
+ISSUER="$(kubectl --context "${KCTX}" get --raw /.well-known/openid-configuration | jq -r .issuer)"
+[[ -n "$ISSUER" ]] || { echo "could not determine cluster OIDC issuer" >&2; exit 1; }
+export NAMESPACE ISSUER IMAGE_TAG
+
+echo "== Applying sam-hub (issuer: ${ISSUER}) =="
+for f in "${SCRIPT_DIR}"/00-*.yaml "${SCRIPT_DIR}"/10-*.yaml; do
+ envsubst '${NAMESPACE} ${ISSUER} ${IMAGE_TAG}' < "$f" | kubectl --context "${KCTX}" apply -f -
+done
+
+echo "== Waiting for sam-hub to be ready =="
+kubectl --context "${KCTX}" -n "${NAMESPACE}" wait --for=condition=available --timeout=180s deployment/sam-hub
+
+echo "== Applying sam-nodes =="
+for line in "${NODE_LINES[@]}"; do
+ node="${line%% *}"; svc="${line#* }"; [[ "$svc" == "$node" ]] && svc=""
+ render_and_apply "$node" "$svc"
+done
+
+echo "== Waiting for sam-nodes =="
+for node in "${NODES[@]}"; do
+ kubectl --context "${KCTX}" -n "${NAMESPACE}" wait --for=condition=available --timeout=180s "deployment/${node}"
+done
+
+echo
+echo "Mesh up. To call a node's MCP API, port-forward it in another shell, e.g.:"
+echo " kubectl --context ${KCTX} -n ${NAMESPACE} port-forward deploy/node-a 9091:8080"
+echo "then:"
+echo " ./bin/mcp-client -url http://127.0.0.1:9091/mcp/events -tool find_remote_tools -args '{}'"
+
+if [[ "${1:-}" != "-s" ]]; then
+ show_cluster_logs
+fi