Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
examples: an agent in a sandbox, a network the admin controls
Antonio Ojea449d84a47706
diff --git a/.gitignore b/.gitignoreindex 56ed5cd4..09fd213c 100644--- a/.gitignore+++ b/.gitignore@@ -69,3 +69,6 @@ mobile/logcat.txtkey.propertiesgoogle-services.json++# Recordings of development/examples/sandboxed-agent/record.sh+development/examples/sandboxed-agent/out/diff --git a/development/examples/sandboxed-agent/Makefile b/development/examples/sandboxed-agent/Makefilenew file mode 100644index 00000000..125adc98--- /dev/null+++ b/development/examples/sandboxed-agent/Makefile@@ -0,0 +1,91 @@+# The admin's side of the demo: a mesh on a public URL, one node in the+# office fronting a model, an MCP server and api.github.com, and the two+# tokens that admit the node and the agent. Each server target runs in the+# foreground; give it its own terminal.+#+# make ollama the office model, in Docker+# make mcp the MCP reference server on :3001+# make mesh sam-one on a public https URL (banner prints it)+# make tokens URL=https://... one token for the node, one for the agent+# make pep URL=https://... the node, with the GitHub credential on its host+# make revoke URL=https://... take api.github.com off the mesh+# make ban URL=... PEER=12D3... cut one member off+# make clean forget everything++DEMO_DIR ?= $(HOME)/sam-demo+REPO_BIN := $(abspath ../../../bin)+SAM_ONE ?= $(if $(wildcard $(REPO_BIN)/sam-one),$(REPO_BIN)/sam-one,sam-one)+SAM_NODE ?= $(if $(wildcard $(REPO_BIN)/sam-node),$(REPO_BIN)/sam-node,sam-node)+# The read-only GitHub token the node presents. Never a flag value: a file.+GITHUB_TOKEN_FILE ?= $(HOME)/.config/sam-demo/github-ro+MODEL ?= gemma3:1b+PORT ?= 8090++.PHONY: ollama mcp mesh tokens secrets pep policy revoke ban clean++ollama:+ docker start sam-demo-ollama 2>/dev/null || \+ docker run -d --name sam-demo-ollama -p 127.0.0.1:11434:11434 -v sam-demo-ollama:/root/.ollama ollama/ollama >/dev/null+ @for _ in $$(seq 1 30); do curl -sf http://127.0.0.1:11434/ >/dev/null && break; sleep 1; done+ docker exec sam-demo-ollama ollama pull $(MODEL)+ curl -s http://127.0.0.1:11434/v1/models++mcp:+ npx -y @modelcontextprotocol/server-everything streamableHttp++mesh:+ $(SAM_ONE) --data-dir "$(DEMO_DIR)/one" --port $(PORT) \+ --tunnel cloudflare --tunnel-install \+ --policy-file policy.json --no-join-token --enroll-qr=false --log-level warn++tokens:+ @test -n "$(URL)" || { echo "make tokens URL=https://... (the API URL from the sam-one banner)"; exit 1; }+ @mkdir -p "$(DEMO_DIR)"+ @$(SAM_ONE) token create --server "$(URL)" --data-dir "$(DEMO_DIR)/one" \+ --max-usages 1 --description "office node" 2>/dev/null \+ | awk '/^Token:/ {print $$2}' > "$(DEMO_DIR)/pep-token"+ @$(SAM_ONE) token create --server "$(URL)" --data-dir "$(DEMO_DIR)/one" \+ --role agent --max-usages 1 --description "agent in the dev sandbox" 2>/dev/null \+ | awk '/^Token:/ {print $$2}' > "$(DEMO_DIR)/agent-token"+ @test -s "$(DEMO_DIR)/pep-token" -a -s "$(DEMO_DIR)/agent-token" || { echo "token create failed"; exit 1; }+ @echo "tokens in $(DEMO_DIR)/pep-token (role sam:role:node) and $(DEMO_DIR)/agent-token (role agent)"++secrets:+ @test -s "$(GITHUB_TOKEN_FILE)" || { echo "GITHUB_TOKEN_FILE=$(GITHUB_TOKEN_FILE) is missing: a read-only fine-grained token for google/sam"; exit 1; }+ @mkdir -p "$(DEMO_DIR)/secrets"+ @install -m 600 "$(GITHUB_TOKEN_FILE)" "$(DEMO_DIR)/secrets/github-ro"+ @echo "credential github-ro in $(DEMO_DIR)/secrets"++pep: secrets+ @test -n "$(URL)" || { echo "make pep URL=https://..."; exit 1; }+ $(SAM_NODE) run --control-plane "$(URL)" \+ --bootstrap-token-path "$(DEMO_DIR)/pep-token" \+ --config pep.yaml --secrets-dir "$(DEMO_DIR)/secrets" \+ --data-dir "$(DEMO_DIR)/pep" --bind-addr= \+ --control-plane-sync-interval 30s++# The admin token: the one sam-one generated into the data dir, unless the+# environment supplies it (then the banner does not show it either).+ADMIN_TOKEN = $${SAM_ADMIN_TOKEN:-$$(cat "$(DEMO_DIR)/one/admin-token")}++policy:+ @test -n "$(URL)" || { echo "make policy URL=https://..."; exit 1; }+ @echo "POST policy.json to $(URL)/policies"+ @curl -sS -X POST "$(URL)/policies" \+ -H "Authorization: Bearer $(ADMIN_TOKEN)" \+ -H 'Content-Type: application/json' --data @policy.json; echo++revoke:+ @test -n "$(URL)" || { echo "make revoke URL=https://..."; exit 1; }+ @echo "POST policy.json without its egress section to $(URL)/policies"+ @jq 'del(.egress)' policy.json | curl -sS -X POST "$(URL)/policies" \+ -H "Authorization: Bearer $(ADMIN_TOKEN)" \+ -H 'Content-Type: application/json' --data @-; echo++ban:+ @test -n "$(URL)" -a -n "$(PEER)" || { echo "make ban URL=https://... PEER=12D3KooW..."; exit 1; }+ @$(SAM_ONE) admin ban "$(PEER)" --server "$(URL)" --data-dir "$(DEMO_DIR)/one"++clean:+ rm -rf "$(DEMO_DIR)"+ docker rm -f sam-demo-ollama >/dev/null 2>&1 || truediff --git a/development/examples/sandboxed-agent/SCRIPT.md b/development/examples/sandboxed-agent/SCRIPT.mdnew file mode 100644index 00000000..52dd28b1--- /dev/null+++ b/development/examples/sandboxed-agent/SCRIPT.md@@ -0,0 +1,177 @@+# An agent in a sandbox, a network the admin controls++A three to four minute recording. Two machines: the admin's workstation+("the office", left) and a developer sandbox with no route into the office+(a GitHub codespace, right). A caption line at the bottom carries the+narration below, so the recording explains itself and every command is on+screen. `record.sh` produces it; the sections below are what it types and+what it says.++## Before recording++On the workstation:++```bash+make build # ./bin/sam-one and ./bin/sam-node+cd development/examples/sandboxed-agent+make ollama # the office model, in Docker+make mcp & # the MCP reference server on :3001+export GITHUB_TOKEN_FILE=~/.config/sam-demo/github-ro # read-only, google/sam pull requests+```++The sandbox: a codespace on `google/sam` (any configuration with Python),+with the SDK installed and `agent.py` in `~/sandbox`:++```bash+python3 -m venv ~/venv && ~/venv/bin/pip install ./sdk/python+mkdir ~/sandbox && cp development/examples/sandboxed-agent/agent.py ~/sandbox/+```++The developer receives the single-use token the admin mints in scene 2 out+of band, as `~/sandbox/agent-token`. The recording does not show a token.++## Scenes++Narration is what the caption pane shows while the commands run.++### 0. The problem++> An agent decides at run time which API it calls and with what. You cannot+> review that in a pull request. Security wants it sandboxed. The developer+> wants the model, the tools and the internal API it needs. A VPN into the+> office is the usual bridge: slow to develop against, and it turns the+> sandbox into a door with credentials inside.++### 1. Two machines++Left, the office. Right, a sandbox somewhere else: a codespace on GitHub.++```bash+# sandbox+curl -m 3 http://office-llm.corp.internal:11434/v1/models+```++> The sandbox has no route into the office. It has a route to one URL, and+> the mesh decides what is behind it.++### 2. The admin starts a mesh and writes one policy++```bash+# office+make mesh+```++> One command: a control plane, a router and a console, on a public https+> URL, with the policy in `policy.json`. No standing join token: every+> member gets a token minted for its role.++```bash+# office+export URL=https://<from the banner>+make tokens URL=$URL+make pep URL=$URL 2>&1 | python3 audit.py+```++> The office node fronts three things: a model on loopback, an MCP server+> on loopback, and `api.github.com` with a read-only token in a file on+> this machine. The policy assigns the destination to the node by its+> label, `site=office`. The role `agent` may call the three by name, and+> `api.github.com` only with `GET` under `/repos/google/sam/`.++`policy.json` is on screen here, shortened to the `agent` role and the+`egress` entry.++### 3. The developer's program joins++```bash+# sandbox+export SAM_CONTROL_PLANE_URL=$URL SAM_BOOTSTRAP_TOKEN_PATH=~/sandbox/agent-token+python agent.py models+```++> The agent is an ordinary Python program with the SDK. It enrolls once,+> with a single-use token for the role `agent`, and gets an identity.+> Nothing else runs in the sandbox: no sidecar, no proxy variables, no VPN.+> The model in the office answers by name.++### 4. A model, a tool++```bash+# sandbox+python agent.py ask+python agent.py tool+```++> A chat completion runs on the office workstation. A tool call reaches+> the MCP server there. Every decision is one line in the node's log.++### 5. An external API, with a credential the sandbox never held++```bash+# sandbox+python agent.py github GET '/repos/google/sam/pulls?state=open&per_page=1'+```++> GitHub answers 200. The node presented the office's token; the request+> the sandbox sent had none.++```bash+# sandbox+python agent.py github POST /repos/google/sam/pulls+python agent.py github GET /user+```++> The agent may try anything. `POST` is outside the grant. `/user` is+> outside the grant. The network answers 403 before GitHub hears of it.++### 6. The admin takes the destination off the mesh++```bash+# office+make revoke URL=$URL+# sandbox+python agent.py github GET '/repos/google/sam/pulls?state=open&per_page=1'+```++> One policy change. The node withdraws `api.github.com` within seconds,+> and the same request finds no service. Nothing to revoke in the sandbox:+> it never had anything.++### 7. The admin cuts the agent off++```bash+# office+make ban URL=$URL PEER=<the agent's peer ID>+# sandbox+python agent.py github GET /user+```++> The identity is banned. No router admits it again.++### 8. Close++> The developer used their own sandbox and wrote a plain program. The+> admin wrote one policy document and read one log. The credential never+> left the office.++## Notes for the narrator++- Grants live in the member's credential for its lifetime (24 hours by+ default, `--control-plane-biscuit-ttl`). Removing a service from a role+ takes effect at the next refresh; removing a destination or banning a+ member takes effect within the node's sync jitter, which is why scenes 6+ and 7 use those two.+- The node polls the control plane every 30 seconds in this demo+ (`--control-plane-sync-interval`) and reacts to policy events within a+ tenth of that. The default is 15 minutes.+- The model's answer is different every take. That is the point of scene 0.++## Recording++```bash+CODESPACE=<name> GITHUB_TOKEN_FILE=~/github-ro ./record.sh # tmux, asciinema, then agg and ffmpeg+```++Outputs `demo.cast`, `demo.gif`, `demo.mp4` and `demo.srt` (the narration+with timestamps, for a voice-over or subtitles) in `out/`, which git+ignores. The published copy is `site/static/demo-sandboxed-agent.mp4`.diff --git a/development/examples/sandboxed-agent/agent.py b/development/examples/sandboxed-agent/agent.pynew file mode 100644index 00000000..1c9e3dff--- /dev/null+++ b/development/examples/sandboxed-agent/agent.py@@ -0,0 +1,159 @@+"""An agent in a sandbox, on the mesh.++The sandbox has no route into the office. This program has one identity on+the mesh and reaches, by name, what the mesh policy grants that identity: a+model, an MCP server and an external API whose credential it never holds.++ python agent.py every step below, in order+ python agent.py models list the office model+ python agent.py ask "..." one chat completion+ python agent.py tool call an MCP tool+ python agent.py github GET /repos/google/sam/pulls?state=open&per_page=1+ python agent.py github POST /repos/google/sam/pulls+ python agent.py github GET /user++SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the token in+SAM_BOOTSTRAP_TOKEN_PATH and keeps identity and credential in SAM_STATE_DIR.+"""++import json+import logging+import os+import sys++import trio+from agent_mesh import AgentMesh++LLM = "inference://office-llm"+TOOLS = "mcp://tools"+GITHUB = "egress://api.github.com"++# py-libp2p narrates every failed dial over several lines; the verdicts this+# program prints are the story. SAM_DEBUG=1 brings the narration back.+if not os.environ.get("SAM_DEBUG"):+ logging.getLogger("libp2p").setLevel(logging.CRITICAL)++mesh = AgentMesh.enroll(+ os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),+ bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),+ # The role the token was minted for; the policy's grants hang off it.+ role=os.environ.get("SAM_ROLE", "agent"),+ state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/sandboxed-agent"),+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",+)+++def say(line: str) -> None:+ print(line, flush=True)+++_providers = {}+++async def reach(session, service):+ """The first provider of service that answers, remembered for this run."""+ if service in _providers:+ return _providers[service]+ providers = await session.discover(service)+ if not providers:+ raise SystemExit(f"nobody on the mesh serves {service}")+ for provider in providers:+ try:+ await session.connect(provider)+ _providers[service] = provider+ return provider+ except (ConnectionError, PermissionError) as err:+ # A provider record can outlive its member; say so in one line.+ print(f"{provider.peer_id[:16]}… not reachable: {str(err).splitlines()[0][:80]}", file=sys.stderr)+ raise SystemExit(f"no provider of {service} is reachable")+++async def models(session):+ pep = await reach(session, LLM)+ say(f"→ GET {LLM} /v1/models")+ resp = await session.request(pep, LLM, "/v1/models")+ ids = [m["id"] for m in resp.json().get("data", [])]+ say(f"← {resp.status} {', '.join(ids)} (served by {pep.peer_id[:16]}…, in the office)")+ return ids+++async def ask(session, question):+ pep = await reach(session, LLM)+ ids = (await session.request(pep, LLM, "/v1/models")).json().get("data", [])+ model = os.environ.get("MODEL") or (ids[0]["id"] if ids else "gemma3:1b")+ say(f"→ POST {LLM} /v1/chat/completions model={model}")+ say(f" {question}")+ resp = await session.request(+ pep, LLM, "/v1/chat/completions",+ method="POST",+ headers={"Content-Type": "application/json"},+ body=json.dumps({"model": model, "messages": [{"role": "user", "content": question}]}),+ )+ if resp.status != 200:+ say(f"← {resp.status} {resp.text[:200]}")+ return+ say(f"← {resp.status} {resp.json()['choices'][0]['message']['content'].strip()}")+++async def tool(session):+ pep = await reach(session, TOOLS)+ tools = await session.list_tools(pep, TOOLS)+ say(f"→ {TOOLS} {len(tools)} tools: {', '.join(t.name for t in tools[:4])}, …")+ say("→ call get-sum(a=2, b=3)")+ result = await session.call_tool(pep, TOOLS, "get-sum", {"a": 2, "b": 3})+ say(f"← {' '.join(result.text)}")+++async def github(session, method, path):+ pep = await reach(session, GITHUB)+ say(f"→ {method} {GITHUB} {path}")+ resp = await session.request(+ pep, GITHUB, path,+ method=method,+ # GitHub refuses requests without a User-Agent; the node forwards it.+ headers={"Accept": "application/vnd.github+json", "User-Agent": "sam-sandboxed-agent"},+ body=b"{}" if method in ("POST", "PUT", "PATCH") else None,+ )+ if resp.status == 200:+ data = resp.json()+ if isinstance(data, list) and data and "number" in data[0]:+ say(f"← {resp.status} #{data[0]['number']} {data[0]['title']}")+ else:+ say(f"← {resp.status} {resp.text[:120]}")+ return+ verdict = resp.headers.get("proxy-status") or resp.headers.get("Proxy-Status") or ""+ say(f"← {resp.status} {verdict or resp.text[:120]}")+++async def main(argv):+ try:+ session_cm = mesh.join()+ session = await session_cm.__aenter__()+ except RuntimeError as err:+ # Every router refused this identity: the admin cut it off.+ raise SystemExit(f"cut off from the mesh: {str(err).splitlines()[0].rstrip(':')}")+ try:+ say(f"on the mesh as {session.peer_id}")+ step = argv[0] if argv else "all"+ if step == "models":+ await models(session)+ elif step == "ask":+ await ask(session, " ".join(argv[1:]) or "In one sentence, in English: why should an agent never hold API credentials?")+ elif step == "tool":+ await tool(session)+ elif step == "github":+ await github(session, argv[1].upper(), argv[2])+ elif step == "all":+ await models(session)+ await ask(session, "In one sentence, in English: why should an agent never hold API credentials?")+ await tool(session)+ await github(session, "GET", "/repos/google/sam/pulls?state=open&per_page=1")+ await github(session, "POST", "/repos/google/sam/pulls")+ await github(session, "GET", "/user")+ else:+ raise SystemExit(__doc__)+ finally:+ await session_cm.__aexit__(None, None, None)+++trio.run(main, sys.argv[1:])diff --git a/development/examples/sandboxed-agent/audit.py b/development/examples/sandboxed-agent/audit.pynew file mode 100644index 00000000..9a44617e--- /dev/null+++ b/development/examples/sandboxed-agent/audit.py@@ -0,0 +1,38 @@+"""Reads a sam-node log on stdin and prints the lines an admin watches: what+the node serves, and one line per authorization decision.++ make pep URL=https://... 2>&1 | python3 audit.py+"""++import json+import os+import re+import sys++AUDIT = re.compile(r"Audit Traceability\s+(\{.*\})\s*$")+KEEP = re.compile(r"\[Egress\] (Serving|Withdrawn|Assignments)|peer banned|SAM Node Online|PeerID:")+# AUDIT_RAW=<file> keeps the unfiltered log next to the filtered view.+raw = open(os.environ["AUDIT_RAW"], "a") if os.environ.get("AUDIT_RAW") else None++for raw_line in sys.stdin:+ if raw:+ raw.write(raw_line)+ raw.flush()+ line = raw_line.rstrip("\n")+ m = AUDIT.search(line)+ if m:+ try:+ d = json.loads(m.group(1))+ except json.JSONDecodeError:+ continue+ verdict = d.get("decision", "?").upper()+ who = f"{d.get('role') or '-'} {d.get('peer_id', '')[:12]}…"+ what = " ".join(x for x in (d.get("method"), d.get("path")) if x) or d.get("protocol", "")+ print(f"{verdict:<5} {who:<22} {what:<40} {d.get('target', '')}", flush=True)+ elif "peer banned" in line:+ peer = re.search(r'"peer":\s*"([^"]+)"', line)+ print(f"BANNED {peer.group(1) if peer else ''}: the control plane cut this member off", flush=True)+ elif KEEP.search(line):+ # Drop the timestamp and logger columns; keep the message.+ msg = line.split("\t")[-1] if "\t" in line else line+ print(msg.strip(), flush=True)diff --git a/development/examples/sandboxed-agent/pep.yaml b/development/examples/sandboxed-agent/pep.yamlnew file mode 100644index 00000000..c9dd6e78--- /dev/null+++ b/development/examples/sandboxed-agent/pep.yaml@@ -0,0 +1,15 @@+# The node in the office. It fronts two things that listen on loopback and+# are reachable from nowhere else; api.github.com is assigned to it by the+# mesh policy (egress.served_by selects the label below), not declared here.+version: "v1alpha1"+labels:+ site: office+services:+ - type: inference+ name: office-llm+ description: "Ollama on the office workstation"+ target_url: "http://127.0.0.1:11434"+ - type: mcp+ name: tools+ description: "MCP reference server"+ target_url: "http://127.0.0.1:3001/mcp"diff --git a/development/examples/sandboxed-agent/policy.json b/development/examples/sandboxed-agent/policy.jsonnew file mode 100644index 00000000..ab213ed6--- /dev/null+++ b/development/examples/sandboxed-agent/policy.json@@ -0,0 +1,21 @@+{+ "roles": [+ {+ "name": "sam:role:node",+ "allowed_services": ["system://sam.catalog"],+ "allowed_targets": ["*"],+ "allowed_labels": ["site=office"]+ },+ {+ "name": "agent",+ "allowed_services": ["inference://office-llm", "mcp://tools", "egress://api.github.com"],+ "allowed_targets": ["*"],+ "http": [+ { "service": "egress://api.github.com", "methods": ["GET"], "paths": ["/repos/google/sam/*"] }+ ]+ }+ ],+ "egress": [+ { "name": "api.github.com", "credential": "github-ro", "served_by": ["site=office"] }+ ]+}diff --git a/development/examples/sandboxed-agent/record.sh b/development/examples/sandboxed-agent/record.shnew file mode 100755index 00000000..f1ae9941--- /dev/null+++ b/development/examples/sandboxed-agent/record.sh@@ -0,0 +1,325 @@+#!/bin/bash+# 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.++# Records SCRIPT.md. A tmux window holds the office (left: mesh, admin,+# node), the sandbox (right: a shell in a codespace) and a caption line+# (bottom). The scenes are typed into the panes at a human pace and paced+# on what appears in them, so every take is the same. asciinema captures+# the window; agg and ffmpeg render it.+#+# CODESPACE=<name> ./record.sh+#+# Needs: make ollama and make mcp already running, ./bin built, the+# GitHub token at $GITHUB_TOKEN_FILE, and the codespace prepared as+# SCRIPT.md describes (SDK in ~/venv, agent.py and agent-token in ~/sandbox).++set -o errexit+set -o nounset+set -o pipefail++CODESPACE=${CODESPACE:?set CODESPACE to the codespace name (gh codespace list)}+HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)+OUT=$HERE/out+SESSION=samdemo+COLS=${COLS:-190}+ROWS=${ROWS:-54}+CAPTION_FILE=/tmp/samdemo-caption.txt+SRT=$OUT/demo.srt+GITHUB_TOKEN_FILE=${GITHUB_TOKEN_FILE:-$HOME/.config/sam-demo/github-ro}+DEMO_DIR=${DEMO_DIR:-$HOME/sam-demo}++mkdir -p "$OUT"+rm -f "$SRT"+: > "$CAPTION_FILE"++# --- helpers ---------------------------------------------------------------++# type_in <pane> <text>: types text like a person and presses Enter.+type_in() {+ local pane=$1 text=$2 i c+ for ((i = 0; i < ${#text}; i++)); do+ c=${text:i:1}+ tmux send-keys -t "$pane" -l -- "$c"+ sleep "0.0$((RANDOM % 5 + 2))"+ done+ sleep 0.3+ tmux send-keys -t "$pane" Enter+ # Let the shell echo the newline before the next keystroke arrives.+ sleep 0.8+}++# wait_for <pane> <regex> [seconds]: waits until the pane shows regex.+wait_for() {+ local pane=$1 re=$2 timeout=${3:-60} i+ for ((i = 0; i < timeout * 2; i++)); do+ if tmux capture-pane -p -t "$pane" -S -300 | grep -qE -- "$re"; then+ return 0+ fi+ sleep 0.5+ done+ echo "timed out waiting for /$re/ in $pane" >&2+ tmux capture-pane -p -t "$pane" -S -40 >&2+ return 1+}++# grab <pane> <regex>: the first match of regex in the pane.+grab() {+ tmux capture-pane -p -t "$1" -S -300 | grep -oE -- "$2" | head -1+}++# count <pane> <regex>: how many lines of the pane match regex.+count() {+ tmux capture-pane -p -t "$1" -S -300 | grep -cE -- "$2" || true+}++# wait_prompt <pane> [seconds]: waits until the pane's last line is a prompt.+wait_prompt() {+ local pane=$1 timeout=${2:-30} i+ for ((i = 0; i < timeout * 4; i++)); do+ if tmux capture-pane -p -t "$pane" | sed -e :a -e '/^\s*$/{$d;N;ba' -e '}' | tail -1 | grep -qE '\$ ?$'; then+ return 0+ fi+ sleep 0.25+ done+ return 0+}++# expect <pane> <command> <regex> [seconds]: types command, then waits for a+# line matching regex that was not on screen before, and for the prompt.+expect() {+ local pane=$1 cmd=$2 re=$3 timeout=${4:-60} before i+ before=$(count "$pane" "$re")+ type_in "$pane" "$cmd"+ for ((i = 0; i < timeout * 2; i++)); do+ if (( $(count "$pane" "$re") > before )); then+ wait_prompt "$pane"+ return 0+ fi+ sleep 0.5+ done+ echo "timed out waiting for new /$re/ in $pane after: $cmd" >&2+ tmux capture-pane -p -t "$pane" -S -40 >&2+ return 1+}++REC_START=+caption_n=0+caption_prev_at=+caption_prev=+# caption <text>: shows text in the caption pane and records it for the srt.+caption() {+ local now+ now=$(date +%s.%N)+ if [[ -n "$REC_START" && -n "$caption_prev" ]]; then+ srt_entry "$caption_prev_at" "$now" "$caption_prev"+ fi+ printf '%s\n' "$1" > "$CAPTION_FILE"+ caption_prev=$1+ caption_prev_at=$now+}++srt_time() { # seconds since REC_START -> HH:MM:SS,mmm+ python3 -c 'import sys; t=float(sys.argv[1])-float(sys.argv[2]); t=max(t,0); h=int(t//3600); m=int(t%3600//60); s=t%60; print(f"{h:02d}:{m:02d}:{int(s):02d},{int((s-int(s))*1000):03d}")' "$1" "$REC_START"+}++srt_entry() {+ caption_n=$((caption_n + 1))+ {+ echo "$caption_n"+ echo "$(srt_time "$1") --> $(srt_time "$2")"+ echo "$3"+ echo+ } >> "$SRT"+}++pause() { sleep "${1:-2}"; }++cleanup() {+ tmux kill-session -t "$SESSION" 2>/dev/null || true+ tmux kill-session -t "${SESSION}-rec" 2>/dev/null || true+}+trap cleanup EXIT++# --- the window -------------------------------------------------------------++cleanup+tmux new-session -d -s "$SESSION" -x "$COLS" -y "$ROWS" -c "$HERE"+tmux set -t "$SESSION" -g pane-border-status top+tmux set -t "$SESSION" -g pane-border-format ' #{pane_title} '+tmux set -t "$SESSION" -g status off+MESH=$(tmux display -p -t "$SESSION:0.0" '#{pane_id}')+CAPTION=$(tmux split-window -P -F '#{pane_id}' -v -l 4 -t "$MESH" -c "$HERE")+SANDBOX=$(tmux split-window -P -F '#{pane_id}' -h -l 50% -t "$MESH" -c "$HERE")+NODE=$(tmux split-window -P -F '#{pane_id}' -v -l 20 -t "$MESH" -c "$HERE")+ADMIN=$(tmux split-window -P -F '#{pane_id}' -v -l 12 -t "$MESH" -c "$HERE")+tmux select-pane -t "$MESH" -T 'office · mesh (sam-one)'+tmux select-pane -t "$ADMIN" -T 'office · admin'+tmux select-pane -t "$NODE" -T 'office · node (what it serves, every decision)'+tmux select-pane -t "$SANDBOX" -T 'developer sandbox · a codespace, no VPN'+tmux select-pane -t "$CAPTION" -T ''++# The caption pane reprints its file whenever it changes.+cat > /tmp/samdemo-caption.py <<'EOF'+import os, sys, textwrap, time+path, cols = sys.argv[1], int(sys.argv[2])+last = None+while True:+ try:+ text = open(path).read().strip()+ except FileNotFoundError:+ text = ""+ if text != last:+ sys.stdout.write("\033[2J\033[H")+ for line in textwrap.wrap(text, cols - 4)[:3]:+ sys.stdout.write(" \033[1m" + line + "\033[0m\n")+ sys.stdout.flush()+ last = text+ time.sleep(0.2)+EOF+tmux send-keys -t "$CAPTION" "python3 /tmp/samdemo-caption.py $CAPTION_FILE $COLS" Enter++# Quiet prompts. The admin token comes from the environment so the banner+# names its source instead of showing it.+ADMIN_TOKEN=$(openssl rand -hex 16)+for p in "$MESH" "$ADMIN" "$NODE"; do+ tmux send-keys -t "$p" "export SAM_ADMIN_TOKEN=$ADMIN_TOKEN GITHUB_TOKEN_FILE=$GITHUB_TOKEN_FILE DEMO_DIR=$DEMO_DIR AUDIT_RAW=$OUT/node.log PS1='office\$ '; clear" Enter+done+rm -f "$OUT/node.log"+tmux send-keys -t "$SANDBOX" "gh codespace ssh -c $CODESPACE" Enter+wait_for "$SANDBOX" '\$\s*$' 120+tmux send-keys -t "$SANDBOX" "PS1='sandbox\$ '; cd ~/sandbox && source ~/venv/bin/activate && rm -rf ~/.config/sam-mesh/sandboxed-agent ~/sandbox/state && clear" Enter+wait_for "$SANDBOX" 'sandbox\$' 30+# A fresh mesh every take; the downloaded cloudflared is kept.+rm -rf "$DEMO_DIR/pep"+if [[ -d "$DEMO_DIR/one" ]]; then+ find "$DEMO_DIR/one" -mindepth 1 -maxdepth 1 ! -name bin -exec rm -rf {} ++fi++# --- record -----------------------------------------------------------------++# The recorder runs in its own tmux session so its pty has the window's size.+tmux new-session -d -s "${SESSION}-rec" -x "$COLS" -y "$ROWS" \+ "asciinema rec -q --overwrite --cols $COLS --rows $ROWS -c 'tmux attach -t $SESSION' '$OUT/demo.cast'"+sleep 2+REC_START=$(date +%s.%N)++caption "An agent decides at run time which API it calls, and with what. You cannot review that in a pull request. Security wants it sandboxed; the developer wants the model, the tools and the internal API it needs."+pause 7+caption "The usual bridge is a VPN into the office: slow to develop against, and it turns the sandbox into a door with credentials inside."+pause 6++# 1. Two machines+caption "Left: the office. Right: a developer sandbox somewhere else, here a GitHub codespace. It has no route into the office."+expect "$SANDBOX" "curl -m 3 http://office-llm.corp.internal:11434/v1/models" 'Could not resolve host|Connection timed out' 10+pause 3++# 2. The mesh and the policy+caption "The admin starts a mesh: a control plane, a router and a console, on a public https URL, with the policy in policy.json. No standing join token."+expect "$MESH" "make mesh" 'SAM standalone mesh is ready' 120+URL=$(grab "$MESH" 'https://[a-z0-9-]+\.trycloudflare\.com')+# A quick tunnel is routed a few seconds after cloudflared prints it, and+# once in a while it dies at once; either way, do not type into a dead URL.+for i in $(seq 1 30); do+ [[ $(curl -s -o /dev/null -w '%{http_code}' "$URL/healthz") == 200 ]] && break+ sleep 2+ if (( i == 30 )); then echo "the tunnel at $URL never answered; abort this take" >&2; exit 1; fi+done+pause 3++caption "One token per member, minted for its role. The office node gets sam:role:node and the label site=office; the agent gets the role agent."+type_in "$ADMIN" "export URL=$URL"+expect "$ADMIN" "make tokens URL=\$URL" 'tokens in' 30+# The developer receives the token out of band; here, over ssh.+gh codespace ssh -c "$CODESPACE" -- 'cat > ~/sandbox/agent-token; chmod 600 ~/sandbox/agent-token' < "$DEMO_DIR/agent-token" 2>/dev/null+pause 2++caption "The policy: the agent may call the model, the MCP server and api.github.com by name, and api.github.com only with GET under /repos/google/sam/. The destination is served by nodes labelled site=office."+type_in "$ADMIN" "jq -c '.roles[1].allowed_services, .roles[1].http[0], .egress[0]' policy.json"+pause 8++caption "The office node fronts a model and an MCP server on loopback. api.github.com is assigned to it by the policy; its read-only token is a file on this machine, read by the node, never by an agent."+type_in "$NODE" "export URL=$URL"+expect "$NODE" "make pep URL=\$URL 2>&1 | python3 audit.py" 'SAM Node Online' 60+pause 4++# 3. The developer's program joins+caption "The agent is an ordinary Python program with the SDK. The admin handed the developer the single-use token out of band. It enrolls once and gets an identity: no sidecar, no proxy variables, no VPN."+type_in "$SANDBOX" "export SAM_CONTROL_PLANE_URL=$URL SAM_BOOTSTRAP_TOKEN_PATH=~/sandbox/agent-token"+expect "$SANDBOX" "python agent.py models" '← 200 gemma3' 90+PEER=$(grab "$SANDBOX" 'on the mesh as 12D3KooW[A-Za-z0-9]+' | awk '{print $NF}')+pause 3++# 4. A model, a tool+caption "A chat completion runs on the office workstation. The answer is different every take; that is the point."+expect "$SANDBOX" "python agent.py ask" '← 200 ' 90+pause 5+caption "A tool call reaches the MCP server in the office. On the left, every decision is one line in the node's log."+expect "$SANDBOX" "python agent.py tool" 'sum of 2 and 3' 60+pause 4++# 5. External API+caption "An external API. GitHub answers 200: the node presented the office's token. The request the sandbox sent had none."+expect "$SANDBOX" "python agent.py github GET '/repos/google/sam/pulls?state=open&per_page=1'" '← 200 #' 60+pause 4+caption "The agent may try anything. POST is outside the grant; /user is outside the grant. The network answers 403 before GitHub hears of it."+expect "$SANDBOX" "python agent.py github POST /repos/google/sam/pulls" 'http_request_denied' 60+expect "$SANDBOX" "python agent.py github GET /user" 'http_request_denied' 60+wait_for "$NODE" 'DENY.*GET /user' 30+pause 5++# 6. Revoke+caption "The admin takes api.github.com off the mesh: one policy change. The node withdraws it within seconds."+expect "$ADMIN" "make revoke URL=\$URL" 'success' 30+wait_for "$NODE" 'Withdrawn egress://api.github.com' 60+pause 2+caption "The same request finds no service. Nothing to revoke in the sandbox: it never had anything."+expect "$SANDBOX" "python agent.py github GET '/repos/google/sam/pulls?state=open&per_page=1'" '← 404' 60+pause 4++# 7. Ban+caption "And when the admin decides this agent is done: the identity is banned, and no router admits it again."+expect "$ADMIN" "make ban URL=\$URL PEER=$PEER" 'banned' 30+wait_for "$NODE" 'BANNED' 30+expect "$SANDBOX" "python agent.py github GET /user" 'cut off from the mesh' 90+pause 4++# 8. Close+caption "The developer used their own sandbox and wrote a plain program. The admin wrote one policy document and read one log. The credential never left the office."+pause 8+caption "sam-mesh.dev"+pause 4++# Ends the recording: the attached client exits with the session.+END=$(date +%s.%N)+srt_entry "$caption_prev_at" "$END" "$caption_prev"+tmux kill-session -t "$SESSION"+for _ in $(seq 1 30); do tmux has-session -t "${SESSION}-rec" 2>/dev/null || break; sleep 1; done++# --- render -------------------------------------------------------------------++# The teardown clears the screen; the recording ends on the closing caption.+python3 - "$OUT/demo.cast" "$END" <<'EOF'+import json, sys+path, end = sys.argv[1], float(sys.argv[2])+lines = open(path).read().splitlines()+cutoff = end - json.loads(lines[0])["timestamp"] - 0.5+kept = [lines[0]] + [l for l in lines[1:] if json.loads(l)[0] <= cutoff]+open(path, "w").write("\n".join(kept) + "\n")+EOF++agg --cols "$COLS" --rows "$ROWS" --font-size 14 --theme monokai --idle-time-limit 30 --last-frame-duration 3 "$OUT/demo.cast" "$OUT/demo.gif"+ffmpeg -y -loglevel error -i "$OUT/demo.gif" -movflags faststart -pix_fmt yuv420p \+ -vf 'scale=trunc(iw/2)*2:trunc(ih/2)*2' "$OUT/demo.mp4"+echo "recorded: $OUT/demo.cast $OUT/demo.gif $OUT/demo.mp4 $SRT"diff --git a/site/content/docs/use-cases/sandboxed-agent.md b/site/content/docs/use-cases/sandboxed-agent.mdnew file mode 100644index 00000000..95f1536d--- /dev/null+++ b/site/content/docs/use-cases/sandboxed-agent.md@@ -0,0 +1,100 @@+---+title: "Sandboxed Agent"+linkTitle: "Sandboxed Agent"+weight: 5+---++An agent runs in a sandbox with no route into the office: here, a GitHub+codespace. Through the mesh it reaches a model and an MCP server that listen+on loopback in the office, and `api.github.com` with a credential it never+holds. The admin decides what it may call, down to the HTTP method and path,+watches every decision, and cuts it off when done.++<video autoplay loop muted playsinline controls style="width: 100%; border-radius: 8px;">+ <source src="../../../demo-sandboxed-agent.mp4" type="video/mp4">+</video>++Source: [`development/examples/sandboxed-agent/`](https://github.com/google/sam/tree/main/development/examples/sandboxed-agent).+The scenes, the narration and the recording recipe are in its+[`SCRIPT.md`](https://github.com/google/sam/blob/main/development/examples/sandboxed-agent/SCRIPT.md).++## The idea++An agentic application is not deterministic: the code decides at run time+which API it calls and with what, so its network behaviour cannot be+reviewed in a pull request. The usual way to give it the model, the tools+and the internal API it needs is a VPN into the corporate network, which is+slow to develop against and turns the sandbox into a door with credentials+inside.++The mesh replaces the VPN with one identity and one policy. The agent is an+ordinary program written with the [Python SDK](../../guides/native-sdks/);+the sandbox needs outbound HTTPS to one URL and nothing else, so any sandbox+works: a container, a microVM, a codespace. What the agent can reach is+decided by name on the admin's side, and the credential for the external+API stays on a node in the office.++## The pieces++**One policy** ([`policy.json`](https://github.com/google/sam/blob/main/development/examples/sandboxed-agent/policy.json)).+The role `agent` may call `inference://office-llm`, `mcp://tools` and+`egress://api.github.com`, the last one only with `GET` under+`/repos/google/sam/`. The destination `api.github.com` is served by nodes+labelled `site=office` with the credential named `github-ro`.++**One node in the office** ([`pep.yaml`](https://github.com/google/sam/blob/main/development/examples/sandboxed-agent/pep.yaml)).+A `sam-node` with the label `site=office` fronts Ollama and an MCP server on+loopback. The control plane assigns `api.github.com` to it because of the+label; the node reads the token from `<--secrets-dir>/github-ro` on every+request and presents it to GitHub. See+[egress destinations](../../guides/egress-destinations/).++**One program in the sandbox** ([`agent.py`](https://github.com/google/sam/blob/main/development/examples/sandboxed-agent/agent.py)).+It enrolls once with a single-use token minted for the role `agent`, then+discovers each service by name and calls it: `/v1/models` and a chat+completion, an MCP tool, and three requests to GitHub of which the policy+allows one.++## Run it yourself++On the office machine, from `development/examples/sandboxed-agent/`:++```bash+make ollama # the office model, in Docker+make mcp # the MCP reference server on :3001, in its own terminal+make mesh # sam-one on a public https URL; copy the API URL from the banner+make tokens URL=$URL # one token for the node, one for the agent+GITHUB_TOKEN_FILE=~/github-ro make pep URL=$URL 2>&1 | python3 audit.py+```++`GITHUB_TOKEN_FILE` is a fine-grained token with read access to pull+requests on `google/sam`, and nothing else; the node is the only process+that reads it.++In the sandbox, with the SDK installed (`pip install ./sdk/python`) and the+agent token the admin handed you:++```bash+export SAM_CONTROL_PLANE_URL=$URL SAM_BOOTSTRAP_TOKEN_PATH=./agent-token+python agent.py # every step, or one of: models, ask, tool, github GET /user+```++Then, back in the office, `make revoke URL=$URL` takes the destination off+the mesh and `make ban URL=$URL PEER=<peer id>` cuts the agent off.++## What to notice++- The request GitHub receives carries the office's token and none of the+ agent's headers. The sandbox never had a credential to leak.+- `POST /repos/google/sam/pulls` and `GET /user` are answered `403` with+ `Proxy-Status: sam-node; error=http_request_denied` by the node, before+ GitHub hears of them. Each is one `DENY` line in the node's log with the+ peer, the role, the method and the path.+- Removing the `egress` entry from the policy withdraws the destination on+ the node within its sync jitter (the example runs with+ `--control-plane-sync-interval 30s`); the same request then finds no+ service. Banning the peer disconnects it and no router admits it again.+- Grants live in a member's credential until it is refreshed (24 hours by+ default, `--control-plane-biscuit-ttl`). Removing a service from a role+ takes effect at that refresh; withdrawing a destination or banning a+ member takes effect at once, which is why the demo uses those two.diff --git a/site/static/demo-sandboxed-agent.mp4 b/site/static/demo-sandboxed-agent.mp4new file mode 100644index 00000000..60ac6f86Binary files /dev/null and b/site/static/demo-sandboxed-agent.mp4 differ