Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs,examples: an OpenShell sandbox on the mesh under its own identity
Antonio Ojeae2c892c01f5f
diff --git a/development/examples/openshell-sandbox/.gitignore b/development/examples/openshell-sandbox/.gitignorenew file mode 100644index 00000000..7e3b24e0--- /dev/null+++ b/development/examples/openshell-sandbox/.gitignore@@ -0,0 +1 @@+run/diff --git a/development/examples/openshell-sandbox/Makefile b/development/examples/openshell-sandbox/Makefilenew file mode 100644index 00000000..b06a8e29--- /dev/null+++ b/development/examples/openshell-sandbox/Makefile@@ -0,0 +1,112 @@+# An agent in an OpenShell sandbox, on the mesh under its own identity.+#+# make up SPIRE, the mesh, the OpenShell gateway; register the provider+# make sandbox NAME=demo give one sandbox a SPIFFE ID, then create it with the provider+# make call NAME=demo from inside the sandbox: list tools, add 2+3 on calc, try payroll+# make rogue a second sandbox with no role: same image, same profile, refused+# make policy push policy.json to the running mesh after editing it+# make down remove the sandboxes and everything `up` created+#+# Needs: docker with the compose plugin, the openshell CLI (0.1.3 or later),+# python3 and curl on this machine. Everything listens on 127.0.0.1 only.++SHELL := /bin/bash+.ONESHELL:+.SHELLFLAGS := -eu -o pipefail -c++NAME ?= demo+GATEWAY ?= openshell-agentmesh+TRUST_DOMAIN := openshell.local+SPIRE := docker compose exec -T --interactive=false spire-server /opt/spire/bin/spire-server+SANDBOX_IMAGE := openshell-agentmesh-sandbox:local++.PHONY: up sandbox call rogue policy status down++up: run/join-token run/api-token run/admin-token+ @command -v openshell >/dev/null || { echo "openshell CLI not found: https://docs.openshell.ai/about/installation"; exit 1; }+ docker compose up -d spire-server spire-oidc+ @for _ in $$(seq 1 30); do $(SPIRE) healthcheck >/dev/null 2>&1 && break; sleep 1; done+ $(SPIRE) healthcheck+ # One join token admits the agent as spiffe://$(TRUST_DOMAIN)/host, the+ # parent of every sandbox entry.+ if [ ! -s run/agent.conf ]; then+ token=$$($(SPIRE) token generate -spiffeID spiffe://$(TRUST_DOMAIN)/host | awk '/^Token:/ {print $$2}')+ test -n "$$token"+ umask 022 && sed "s|\$${SPIRE_JOIN_TOKEN}|$$token|" spire/agent.conf.in > run/agent.conf+ fi+ docker build -q -t $(SANDBOX_IMAGE) sandbox >/dev/null+ docker compose up -d --build+ @for _ in $$(seq 1 60); do curl -sf http://127.0.0.1:8085/healthz >/dev/null && break; sleep 1; done+ curl -sf http://127.0.0.1:8085/healthz >/dev/null+ openshell gateway list 2>/dev/null | grep -q '^$(GATEWAY)\b' || openshell gateway add http://127.0.0.1:8080 --name $(GATEWAY)+ openshell profile import -f openshell/provider-profile.yaml+ openshell provider list 2>/dev/null | grep -q '^agentmesh\b' || openshell provider create --name agentmesh --type agentmesh --runtime-credentials+ @echo+ @echo "Mesh console: http://127.0.0.1:8070/console/ (admin token in run/admin-token)"+ @echo "Next: make sandbox NAME=demo && make call NAME=demo"++# The sandbox's identity is a SPIRE registration entry keyed on the label+# OpenShell puts on the sandbox's supervisor container. The mesh policy+# (policy.json) says what that identity may call.+sandbox:+ entry=$$($(SPIRE) entry show -spiffeID spiffe://$(TRUST_DOMAIN)/sandbox/$(NAME) | awk '/^Entry ID/ {print $$4}')+ if [ -z "$$entry" ]; then+ entry=$$($(SPIRE) entry create \+ -parentID spiffe://$(TRUST_DOMAIN)/host \+ -spiffeID spiffe://$(TRUST_DOMAIN)/sandbox/$(NAME) \+ -selector docker:label:openshell.ai/sandbox-name:$(NAME) | awk '/^Entry ID/ {print $$4}')+ fi+ test -n "$$entry"+ # The agent learns about the entry on its next sync and mints the SVID.+ for _ in $$(seq 1 30); do+ docker compose logs --no-log-prefix spire-agent 2>/dev/null | grep -q "entry_id=$$entry " && break+ sleep 1+ done+ openshell sandbox create --name $(NAME) --from $(SANDBOX_IMAGE) --provider agentmesh --detach -- sleep infinity+ @echo "sandbox $(NAME) is spiffe://$(TRUST_DOMAIN)/sandbox/$(NAME) (SPIRE entry $$entry); try: make call NAME=$(NAME)"++call:+ @echo "== tools the mesh offers sandbox $(NAME)"+ python3 mcp.py tools $(NAME)+ @echo "== mcp://calc, allowed for the sandbox role"+ python3 mcp.py add $(NAME) calc 2 3+ @echo "== mcp://payroll, not in the sandbox role"+ python3 mcp.py add $(NAME) payroll 2 3 || true++rogue:+ $(MAKE) sandbox NAME=rogue+ @echo "== rogue has a SPIFFE ID but policy.json binds it to no role"+ $(MAKE) call NAME=rogue || true+ @echo "== to let it in: add user:spiffe://$(TRUST_DOMAIN)/sandbox/rogue to the sandbox role in policy.json, then make policy"++# Replaces the whole mesh policy. Nodes pick it up within their sync interval;+# a sandbox gets the new roles when the OpenShell supervisor next renews its+# cached credential (cache_ttl_seconds in the provider profile).+policy:+ curl -sS -X POST http://127.0.0.1:8070/policies \+ -H "Authorization: Bearer $$(cat run/admin-token)" \+ -H 'Content-Type: application/json' --data-binary @policy.json+ @echo++status:+ docker compose ps+ openshell sandbox list+ $(SPIRE) entry show++down:+ -openshell sandbox delete demo rogue 2>/dev/null+ -openshell provider delete agentmesh 2>/dev/null+ -openshell profile delete agentmesh 2>/dev/null+ -openshell gateway remove $(GATEWAY) 2>/dev/null+ docker compose down -v --remove-orphans+ rm -rf run+ @echo "left in place: /var/lib/openshell (OpenShell state and the SPIRE agent socket directory)"++run/join-token:+ mkdir -p run && umask 022 && printf 'mesh_tok_%s' "$$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')" > $@++run/admin-token:+ mkdir -p run && umask 022 && printf 'mesh_adm_%s' "$$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')" > $@++run/api-token:+ mkdir -p run && umask 022 && head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n' > $@diff --git a/development/examples/openshell-sandbox/README.md b/development/examples/openshell-sandbox/README.mdnew file mode 100644index 00000000..fa21dcf1--- /dev/null+++ b/development/examples/openshell-sandbox/README.md@@ -0,0 +1,28 @@+# An OpenShell sandbox on the mesh++Everything the guide at `site/content/docs/guides/openshell.md` walks through,+as one `docker compose` project and a Makefile:++- a SPIRE server, agent and OIDC discovery provider for the trust domain+ `openshell.local`, attesting OpenShell sandbox supervisors by their Docker+ labels so every sandbox has its own SPIFFE ID;+- `agentmesh-one` trusting that SPIRE issuer, an edge `agentmesh-node` beside+ the sandboxes, and an office `agentmesh-node` publishing a calculator as+ `mcp://calc` and `mcp://payroll`;+- the OpenShell gateway container from the OpenShell release, with the one+ configuration line that projects the SPIRE Workload API into sandbox+ supervisors, and a provider profile whose token grant trades the sandbox's+ JWT-SVID for a mesh credential.++```bash+make up # start it all, register the gateway and the provider+make sandbox NAME=demo # one SPIFFE ID, one sandbox+make call NAME=demo # tools, calc allowed, payroll refused+make rogue # a sandbox the policy does not bind: refused+make policy # push policy.json after you edit it+make down+```++`run/` holds generated tokens and the rendered SPIRE agent configuration and is+not committed. OpenShell keeps its state under `/var/lib/openshell`, where the+SPIRE agent socket also lives.diff --git a/development/examples/openshell-sandbox/compose.yaml b/development/examples/openshell-sandbox/compose.yamlnew file mode 100644index 00000000..a72380b5--- /dev/null+++ b/development/examples/openshell-sandbox/compose.yaml@@ -0,0 +1,189 @@+# An OpenShell gateway, a SPIRE trust domain for its sandboxes, and a small+# Agent Mesh, all on one machine. `make up` in this directory brings it up in+# order; the guide at site/content/docs/guides/openshell.md walks through it.+#+# Host ports (loopback only):+# 8080 OpenShell gateway API (what the openshell CLI talks to)+# 8085 OpenShell gateway health+# 8070 agentmesh-one API and console+# 8090 edge agentmesh-node API: the token endpoint the sandbox supervisor+# calls, and the /mcp and /v1 endpoints the sandbox reaches++name: openshell-agentmesh++x-agentmesh-node: &agentmesh-node+ image: ${AGENTMESH_NODE_IMAGE:-ghcr.io/google/agentmesh-node:${AGENTMESH_VERSION:-latest}}+ restart: unless-stopped+ depends_on:+ agentmesh-one:+ condition: service_started++services:+ # ---------------------------------------------------------------- SPIRE ----+ spire-server:+ image: ghcr.io/spiffe/spire-server:${SPIRE_VERSION:-1.14.2}+ restart: unless-stopped+ # The image runs as 1000:1000, but the named volumes below are created+ # root-owned. Root keeps this local example to one file.+ user: "0"+ command: ["-config", "/etc/spire/server.conf"]+ volumes:+ - ./spire/server.conf:/etc/spire/server.conf:ro+ - spire-server-data:/run/spire/data+ - spire-server-socket:/tmp/spire-server/private++ spire-oidc:+ image: ghcr.io/spiffe/oidc-discovery-provider:${SPIRE_VERSION:-1.14.2}+ restart: unless-stopped+ user: "0"+ command: ["-config", "/etc/spire/oidc.conf"]+ depends_on: [spire-server]+ volumes:+ - ./spire/oidc.conf:/etc/spire/oidc.conf:ro+ - spire-server-socket:/tmp/spire-server/private++ spire-agent:+ image: ghcr.io/spiffe/spire-agent:${SPIRE_VERSION:-1.14.2}+ restart: unless-stopped+ # The docker workload attestor locates a caller by its PID, so the agent+ # shares the host PID namespace and reads the Docker socket.+ pid: host+ user: "0"+ command: ["-config", "/run/spire/agent.conf"]+ depends_on: [spire-server]+ volumes:+ - ./run/agent.conf:/run/spire/agent.conf:ro+ - /var/run/docker.sock:/var/run/docker.sock:ro+ - spire-agent-data:/run/spire/agent-data+ # Host path the OpenShell gateway names in provider_spiffe_workload_api_socket.+ - type: bind+ source: /var/lib/openshell/spire-agent+ target: /run/spire/sockets+ bind:+ create_host_path: true++ # ----------------------------------------------------------- Agent Mesh ----+ agentmesh-one:+ image: ${AGENTMESH_ONE_IMAGE:-ghcr.io/google/agentmesh-one:${AGENTMESH_VERSION:-latest}}+ restart: unless-stopped+ command:+ - --bind-address=0.0.0.0+ - --port=8080+ - --data-dir=/data+ - --policy-file=/etc/agentmesh/policy.json+ - --token-path=/run/agentmesh/join-token+ - --admin-token-path=/run/agentmesh/admin-token+ # Trust SPIRE as a workload identity issuer: a JWT-SVID whose aud is+ # "agentmesh" becomes a mesh identity, with the roles policy.json binds.+ - --workload-issuer=http://spire-oidc:8008+ - --allowed-audiences=agentmesh+ - --enroll-qr=false+ depends_on: [spire-oidc]+ ports:+ - "127.0.0.1:8070:8080"+ volumes:+ - ./policy.json:/etc/agentmesh/policy.json:ro+ - ./run/join-token:/run/agentmesh/join-token:ro+ - ./run/admin-token:/run/agentmesh/admin-token:ro+ - agentmesh-one-data:/data++ # The node beside the sandboxes. Its API is the sandbox's only door to the+ # mesh and the token endpoint the OpenShell supervisor uses.+ edge-node:+ <<: *agentmesh-node+ command:+ - run+ - --control-plane=http://agentmesh-one:8080+ # Plain HTTP to the control plane is fine on this private Compose network.+ - --insecure-control-plane+ - --bootstrap-token-path=/run/agentmesh/join-token+ - --api-token-path=/run/agentmesh/api-token+ - --data-dir=/data+ - --bind-addr=0.0.0.0:8080+ # Pull policy changes every 30s instead of the 15m default, so `make+ # policy` shows up quickly.+ - --control-plane-sync-interval=30s+ ports:+ - "127.0.0.1:8090:8080"+ volumes:+ - ./run/join-token:/run/agentmesh/join-token:ro+ - ./run/api-token:/run/agentmesh/api-token:ro+ - edge-node-data:/data++ # The node in the office, publishing the calculator as two MCP services.+ office-node:+ <<: *agentmesh-node+ command:+ - run+ - --control-plane=http://agentmesh-one:8080+ - --insecure-control-plane+ - --bootstrap-token-path=/run/agentmesh/join-token+ - --api-token-path=/run/agentmesh/api-token+ - --data-dir=/data+ - --bind-addr=+ - --config=/etc/agentmesh/office.yaml+ - --control-plane-sync-interval=30s+ depends_on:+ agentmesh-one:+ condition: service_started+ calc-mcp:+ condition: service_started+ volumes:+ - ./office.yaml:/etc/agentmesh/office.yaml:ro+ - ./run/join-token:/run/agentmesh/join-token:ro+ - ./run/api-token:/run/agentmesh/api-token:ro+ - office-node-data:/data++ calc-mcp:+ build: ../calc-mcp+ restart: unless-stopped++ # ------------------------------------------------------------ OpenShell ----+ # deploy/docker/docker-compose.yml from the OpenShell release, unchanged+ # except for the port numbers and the config file in ./openshell.+ openshell-init:+ image: &openshell-image ghcr.io/nvidia/openshell/gateway:${OPENSHELL_VERSION:-0.1.3}+ user: "0"+ restart: "no"+ command: ["generate-certs", "--output-dir", "/var/lib/openshell/tls"]+ environment:+ HOME: /var/lib/openshell+ volumes:+ - &openshell-data+ type: bind+ source: /var/lib/openshell+ target: /var/lib/openshell+ bind:+ create_host_path: true++ openshell-gateway:+ image: *openshell-image+ restart: unless-stopped+ depends_on:+ openshell-init:+ condition: service_completed_successfully+ command: []+ user: "0"+ ports:+ - "127.0.0.1:8080:8080"+ - "127.0.0.1:8085:8085"+ volumes:+ - /var/run/docker.sock:/var/run/docker.sock+ - *openshell-data+ - type: bind+ source: ./openshell/gateway.toml+ target: /etc/openshell/gateway.toml+ read_only: true+ environment:+ OPENSHELL_GATEWAY_CONFIG: /etc/openshell/gateway.toml+ OPENSHELL_DB_URL: "sqlite:/var/lib/openshell/gateway.db?mode=rwc"+ XDG_DATA_HOME: /var/lib/openshell+ HOME: /var/lib/openshell++volumes:+ spire-server-data:+ spire-server-socket:+ spire-agent-data:+ agentmesh-one-data:+ edge-node-data:+ office-node-data:diff --git a/development/examples/openshell-sandbox/mcp.py b/development/examples/openshell-sandbox/mcp.pynew file mode 100755index 00000000..ad119ed2--- /dev/null+++ b/development/examples/openshell-sandbox/mcp.py@@ -0,0 +1,100 @@+#!/usr/bin/env python3+# Calls the edge node's MCP server from inside an OpenShell sandbox, the way an+# agent would: plain HTTP to host.openshell.internal, no credential in hand.+# The OpenShell supervisor adds the sandbox's mesh credential on the way out.+#+# mcp.py tools SANDBOX [SERVICE] tools the mesh offers this sandbox+# mcp.py add SANDBOX SERVICE A B call mcp://SERVICE/add through the mesh+import json+import subprocess+import sys++NODE = "http://host.openshell.internal:8090/mcp"+++def rpc(sandbox, tool, arguments):+ body = json.dumps({+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": {"name": tool, "arguments": arguments},+ })+ out = subprocess.run(+ ["openshell", "sandbox", "exec", "--name", sandbox, "--no-tty", "--",+ "curl", "-sS", "--max-time", "60", "-w", "\n%{http_code}", NODE,+ "-H", "Content-Type: application/json",+ "-H", "Accept: application/json, text/event-stream",+ # OpenShell inspects MCP and wants the revision stated, as a real+ # client does after initialize.+ "-H", "MCP-Protocol-Version: 2025-11-25",+ "-d", body],+ check=True, capture_output=True, text=True,+ ).stdout+ out, _, status = out.rpartition("\n")+ # Streamable HTTP answers as JSON or as one SSE message.+ payload = out+ if out.lstrip().startswith("event:") or "\ndata: " in out:+ payload = "".join(line[6:] for line in out.splitlines() if line.startswith("data: "))+ try:+ reply = json.loads(payload)+ except ValueError:+ sys.exit(f"{tool}: HTTP {status}: {out.strip()[:300]}")+ if "error" in reply:+ error = reply["error"]+ sys.exit(f"{tool}: HTTP {status}: {error.get('message', error) if isinstance(error, dict) else error}")+ result = reply["result"]+ text = "\n".join(c.get("text", "") for c in result.get("content", []) if c.get("type") == "text")+ if result.get("isError"):+ return None, text+ try:+ return json.loads(text), text+ except ValueError:+ return text, text+++def tools(sandbox, service=None):+ args = {"service_name": service} if service else {}+ rows, text = rpc(sandbox, "find_remote_tools", args)+ if rows is None:+ sys.exit(f"find_remote_tools refused: {text}")+ if isinstance(rows, dict):+ rows = rows.get("tools") or rows.get("results") or [rows]+ for row in rows:+ if "error" in row:+ print(f" {row.get('peer_id', '?')[:16]}… {row['error']}")+ else:+ print(f" {row['peer_id'][:16]}… {row['tool_name']:<24} {row.get('description', '')}")+ return rows+++def add(sandbox, service, a, b):+ rows = tools(sandbox, service)+ peers = {r["peer_id"] for r in rows if r.get("tool_name") == f"mcp://{service}/add"}+ if not peers:+ # Discovery already hides what the policy refuses. Ask a peer anyway, so+ # the refusal itself is visible.+ print(f" (no tool of mcp://{service} is visible to this sandbox; calling the office node directly)")+ peers = {r["peer_id"] for r in rpc(sandbox, "discover_remote_services", {"type": "mcp"})[0] or []}+ if not peers:+ print(f"mcp://{service}/add({a}, {b}) -> refused: the mesh shows this sandbox no MCP provider at all (no role binds its identity)")+ sys.exit(3)+ peer = sorted(peers)[0]+ result, text = rpc(sandbox, "call_remote_tool", {+ "peer_id": peer,+ "tool_name": f"mcp://{service}/add",+ "arguments": {"a": float(a), "b": float(b)},+ })+ if result is None:+ print(f"mcp://{service}/add({a}, {b}) -> refused: {text}")+ sys.exit(3)+ print(f"mcp://{service}/add({a}, {b}) = {text}")+++if __name__ == "__main__":+ cmd, *rest = sys.argv[1:] or ["help"]+ if cmd == "tools" and 1 <= len(rest) <= 2:+ tools(*rest)+ elif cmd == "add" and len(rest) == 4:+ add(*rest)+ else:+ sys.exit(__doc__ or "usage: mcp.py tools SANDBOX [SERVICE] | add SANDBOX SERVICE A B")diff --git a/development/examples/openshell-sandbox/office.yaml b/development/examples/openshell-sandbox/office.yamlnew file mode 100644index 00000000..3f269126--- /dev/null+++ b/development/examples/openshell-sandbox/office.yaml@@ -0,0 +1,14 @@+# The node in the office. It publishes two MCP services backed by the same+# calculator so the policy can allow one and refuse the other.+version: "v1alpha1"+labels:+ site: office+services:+ - type: mcp+ name: calc+ description: "calculator MCP server in the office"+ target_url: "http://calc-mcp:7777/mcp"+ - type: mcp+ name: payroll+ description: "an MCP server the sandbox role may not call"+ target_url: "http://calc-mcp:7777/mcp"diff --git a/development/examples/openshell-sandbox/openshell/gateway.toml b/development/examples/openshell-sandbox/openshell/gateway.tomlnew file mode 100644index 00000000..14cefea6--- /dev/null+++ b/development/examples/openshell-sandbox/openshell/gateway.toml@@ -0,0 +1,34 @@+# OpenShell gateway configuration: deploy/docker/gateway.toml from the OpenShell+# release, plus the one line that projects the SPIRE agent's Workload API into+# every sandbox supervisor (provider_spiffe_workload_api_socket).+[openshell]+version = 2++[openshell.gateway]+bind_address = "127.0.0.1:8080"+# Health listens on all container interfaces so Compose can publish it on+# the host loopback.+health_bind_address = "0.0.0.0:8085"+log_level = "info"+compute_driver = "docker"+disable_tls = true++[openshell.gateway.auth]+allow_unauthenticated_users = true++[openshell.gateway.gateway_jwt]+signing_key_path = "/var/lib/openshell/tls/jwt/signing.pem"+public_key_path = "/var/lib/openshell/tls/jwt/public.pem"+kid_path = "/var/lib/openshell/tls/jwt/kid"+gateway_id = "openshell-agentmesh"++[openshell.drivers.docker]+default_image = "nvcr.io/nvidia/base/ubuntu:24.04"+sandbox_runtime_image = "ghcr.io/nvidia/openshell/sandbox:0.1.3"+supervisor_image = "ghcr.io/nvidia/openshell/supervisor:0.1.3"+image_pull_policy = "if_not_present"+sandbox_label = "openshell"+app_armor_profile = "Unconfined"+# Host path of the SPIRE agent socket. The supervisor of each sandbox fetches+# the sandbox's JWT-SVID here when a provider token grant needs one.+provider_spiffe_workload_api_socket = "/var/lib/openshell/spire-agent/agent.sock"diff --git a/development/examples/openshell-sandbox/openshell/provider-profile.yaml b/development/examples/openshell-sandbox/openshell/provider-profile.yamlnew file mode 100644index 00000000..dde3e655--- /dev/null+++ b/development/examples/openshell-sandbox/openshell/provider-profile.yaml@@ -0,0 +1,51 @@+# OpenShell provider profile for an Agent Mesh node reachable from the gateway+# host. The credential is not stored anywhere: for each sandbox the supervisor+# trades the sandbox's JWT-SVID at the node's token endpoint (RFC 7523 client+# assertion) for a Biscuit bound to that identity, caches it, and injects it as+# X-Mesh-Authentication on every request the sandbox makes to the node.+id: agentmesh+display_name: Agent Mesh+description: Mesh services and models through a local agentmesh-node, under the sandbox's own identity+category: other++credentials:+ - name: mesh_token+ description: Biscuit the mesh issues for this sandbox's SPIFFE identity+ required: false+ # Injected as "X-Mesh-Authentication: Bearer <biscuit>".+ auth_style: bearer+ header_name: X-Mesh-Authentication+ token_grant:+ grant_type: client_credentials+ token_endpoint: http://127.0.0.1:8090/oauth/token+ # The aud claim of the JWT-SVID; the control plane accepts it with+ # --allowed-audiences.+ jwt_svid_audience: agentmesh+ client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-spiffe+ # How long the supervisor keeps a Biscuit before trading a fresh SVID for+ # a new one; a policy change reaches a sandbox within this time.+ cache_ttl_seconds: 60++endpoints:+ # The node's MCP server: discover and call tools across the mesh.+ - host: host.openshell.internal+ port: 8090+ path: /mcp+ protocol: mcp+ enforcement: enforce+ allowed_ips: [127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16]+ mcp:+ allow_all_known_mcp_methods: true+ rules:+ - allow: {}+ # The node's OpenAI-compatible endpoint for models published on the mesh.+ - host: host.openshell.internal+ port: 8090+ path: /v1/**+ protocol: rest+ access: read-write+ enforcement: enforce+ allowed_ips: [127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16]++binaries:+ - /**diff --git a/development/examples/openshell-sandbox/policy.json b/development/examples/openshell-sandbox/policy.jsonnew file mode 100644index 00000000..b4d2320b--- /dev/null+++ b/development/examples/openshell-sandbox/policy.json@@ -0,0 +1,26 @@+{+ "roles": [+ {+ "name": "mesh:role:node",+ "allowed_services": ["*"],+ "allowed_targets": ["*"],+ "allowed_labels": ["*"]+ },+ {+ "name": "mesh:role:router",+ "allowed_services": ["*"],+ "allowed_targets": ["*"]+ },+ {+ "name": "sandbox",+ "allowed_services": ["system://mesh.catalog", "mcp://calc"],+ "allowed_targets": ["*"]+ }+ ],+ "bindings": [+ {+ "role": "sandbox",+ "members": ["user:spiffe://openshell.local/sandbox/demo"]+ }+ ]+}diff --git a/development/examples/openshell-sandbox/sandbox/Dockerfile b/development/examples/openshell-sandbox/sandbox/Dockerfilenew file mode 100644index 00000000..ea66c9dd--- /dev/null+++ b/development/examples/openshell-sandbox/sandbox/Dockerfile@@ -0,0 +1,17 @@+# The sandbox image: Ubuntu with curl and python3 for the walkthrough, built+# the way OpenShell's bring-your-own-container example does it. An agent image+# (Claude Code, Codex, Gemini CLI, ...) takes the same place.+FROM nvcr.io/nvidia/base/ubuntu:24.04++RUN apt-get update \+ && apt-get install -y --no-install-recommends \+ bash ca-certificates curl iproute2 nftables python3 \+ && rm -rf /var/lib/apt/lists/* \+ && if getent passwd ubuntu >/dev/null; then userdel ubuntu; fi \+ && if getent group ubuntu >/dev/null; then groupdel ubuntu; fi \+ && groupadd --gid 1000 sandbox \+ && useradd --uid 1000 --gid sandbox --create-home --shell /bin/bash sandbox \+ && install -d -o sandbox -g sandbox /sandbox++WORKDIR /sandbox+USER sandbox:sandboxdiff --git a/development/examples/openshell-sandbox/spire/agent.conf.in b/development/examples/openshell-sandbox/spire/agent.conf.innew file mode 100644index 00000000..61ac3f67--- /dev/null+++ b/development/examples/openshell-sandbox/spire/agent.conf.in@@ -0,0 +1,34 @@+# SPIRE agent for the OpenShell sandbox example. It serves the Workload API on+# a host directory that the OpenShell gateway projects into every sandbox+# supervisor, and attests those supervisors by their Docker labels.+agent {+ data_dir = "/run/spire/agent-data"+ log_level = "INFO"+ server_address = "spire-server"+ server_port = "8081"+ socket_path = "/run/spire/sockets/agent.sock"+ trust_domain = "openshell.local"+ insecure_bootstrap = true+ # Written by `make up` after the server mints it.+ join_token = "${SPIRE_JOIN_TOKEN}"+}++plugins {+ NodeAttestor "join_token" {+ plugin_data {}+ }+ KeyManager "disk" {+ plugin_data {+ directory = "/run/spire/agent-data"+ }+ }+ # The caller of the Workload API is an OpenShell supervisor container. The+ # plugin finds its container through the host PID namespace and turns the+ # container's labels into selectors, so one registration entry per+ # openshell.ai/sandbox-name label gives each sandbox its own SPIFFE ID.+ WorkloadAttestor "docker" {+ plugin_data {+ docker_socket_path = "unix:///var/run/docker.sock"+ }+ }+}diff --git a/development/examples/openshell-sandbox/spire/oidc.conf b/development/examples/openshell-sandbox/spire/oidc.confnew file mode 100644index 00000000..acdef0a0--- /dev/null+++ b/development/examples/openshell-sandbox/spire/oidc.conf@@ -0,0 +1,12 @@+# SPIRE OIDC Discovery Provider. Serves /.well-known/openid-configuration and+# /keys for the trust domain over plain HTTP on the Compose network, which is+# all agentmesh-one needs to verify a sandbox JWT-SVID.+log_level = "INFO"+domains = ["spire-oidc"]+allow_insecure_scheme = true+insecure_addr = ":8008"+jwt_issuer = "http://spire-oidc:8008"++server_api {+ address = "unix:///tmp/spire-server/private/api.sock"+}diff --git a/development/examples/openshell-sandbox/spire/server.conf b/development/examples/openshell-sandbox/spire/server.confnew file mode 100644index 00000000..251e5d43--- /dev/null+++ b/development/examples/openshell-sandbox/spire/server.conf@@ -0,0 +1,32 @@+# SPIRE server for the OpenShell sandbox example. One trust domain for the+# host; the OIDC discovery provider publishes its JWT signing keys so the Agent+# Mesh control plane can verify sandbox JWT-SVIDs by issuer.+server {+ bind_address = "0.0.0.0"+ bind_port = "8081"+ socket_path = "/tmp/spire-server/private/api.sock"+ trust_domain = "openshell.local"+ data_dir = "/run/spire/data"+ log_level = "INFO"+ # The iss claim of every JWT-SVID. agentmesh-one trusts exactly this issuer+ # (--workload-issuer) and fetches its keys from spire-oidc.+ jwt_issuer = "http://spire-oidc:8008"+ default_jwt_svid_ttl = "5m"+}++plugins {+ DataStore "sql" {+ plugin_data {+ database_type = "sqlite3"+ connection_string = "/run/spire/data/datastore.sqlite3"+ }+ }+ NodeAttestor "join_token" {+ plugin_data {}+ }+ KeyManager "disk" {+ plugin_data {+ keys_path = "/run/spire/data/keys.json"+ }+ }+}diff --git a/site/content/docs/guides/_index.md b/site/content/docs/guides/_index.mdindex 18d4be8a..f657265f 100644--- a/site/content/docs/guides/_index.md+++ b/site/content/docs/guides/_index.md@@ -8,6 +8,7 @@ aliases:---Step-by-step pages for common tasks: publish a service, connect an agent-client, enroll machines that cannot log in, and deploy a control plane on-Kubernetes, Cloud Run, SkyPilot or a GitHub codespace. Each page assumes-that you have read the [quick start](../getting-started/quickstart/).+client, enroll machines that cannot log in, put an agent in an OpenShell+sandbox on the mesh, and deploy a control plane on Kubernetes, Cloud Run,+SkyPilot or a GitHub codespace. Each page assumes that you have read the+[quick start](../getting-started/quickstart/).diff --git a/site/content/docs/guides/openshell.md b/site/content/docs/guides/openshell.mdnew file mode 100644index 00000000..cb1d5694--- /dev/null+++ b/site/content/docs/guides/openshell.md@@ -0,0 +1,318 @@+---+title: "OpenShell sandboxes"+linkTitle: "OpenShell sandboxes"+weight: 4+---++This guide puts an agent that runs in an [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)+sandbox on the mesh under the sandbox's own identity. The sandbox holds no+credential. The OpenShell supervisor outside the sandbox proves who the+sandbox is with a SPIFFE JWT-SVID, the mesh turns that proof into a+credential with the roles your policy binds to that identity, and the+supervisor attaches the credential to every request the sandbox makes to+the mesh. Revoking a sandbox is a policy change; no token has to be+rotated and nothing in the sandbox has to change.++Nothing here modifies OpenShell. The release images and the `openshell` CLI+are used as published; the integration is one configuration line in the+gateway and one provider profile.++The whole setup runs on one Linux machine with Docker:+[`development/examples/openshell-sandbox/`](https://github.com/google/agentmesh/tree/main/development/examples/openshell-sandbox)+in the repository has the Compose project and a Makefile for every step+below.++## How the pieces fit++```mermaid+flowchart LR+ subgraph Sandbox["OpenShell sandbox (no credential)"]+ Agent["agent"]+ end+ subgraph Host["gateway host"]+ Sup["OpenShell supervisor<br/>(host network, one per sandbox)"]+ Spire["SPIRE agent<br/>Workload API"]+ Edge["edge agentmesh-node<br/>127.0.0.1:8090"]+ One["agentmesh-one<br/>control plane + router"]+ Office["office agentmesh-node<br/>mcp://calc, mcp://payroll"]+ end+ Agent -- "POST /mcp" --> Sup+ Sup -- "FetchJWTSVID" --> Spire+ Sup -- "POST /oauth/token<br/>client_credentials + JWT-SVID" --> Edge+ Edge -- "/token/exchange" --> One+ Sup -- "X-Mesh-Authentication: Bearer biscuit" --> Edge+ Edge -- "mesh stream, caller's biscuit" --> Office+```++1. The agent sends a plain MCP request to `host.openshell.internal:8090`. It+ does not know about the mesh credential.+2. The supervisor applies the sandbox's network policy. The request matches+ the `agentmesh` provider, whose credential is a token grant, so the+ supervisor asks the SPIRE agent for a JWT-SVID. The SPIRE agent attests+ the supervisor by the labels on its container and answers with the SPIFFE+ ID registered for that sandbox name.+3. The supervisor posts the JWT-SVID to the edge node's token endpoint as an+ RFC 7523 client assertion (`grant_type=client_credentials`). The node+ exchanges it at the control plane, which verifies the SVID against SPIRE's+ OIDC discovery document and mints a Biscuit carrying the roles bound to+ `user:spiffe://openshell.local/sandbox/<name>`.+4. The supervisor caches the Biscuit and injects it as+ `X-Mesh-Authentication: Bearer …` on this and later requests. The edge node+ forwards the request into the mesh under that identity, and the office+ node enforces the policy on its side.++## Before you start++- Docker Engine with the Compose plugin, running as root (the OpenShell+ gateway keeps its state in `/var/lib/openshell`).+- The `openshell` CLI, 0.1.3 or later, from the+ [OpenShell installation page](https://docs.openshell.ai/about/installation).+- `agentmesh-one` and `agentmesh-node` images newer than v0.1.0-rc.9, which+ is when the node's token endpoint learned the client assertion grant. The+ Compose project uses the `latest` images; set `AGENTMESH_VERSION` to pin a+ release.+- `python3` and `curl`.++```bash+cd development/examples/openshell-sandbox+```++## 1. Identity: SPIRE for the sandboxes++Three SPIRE containers give the gateway host a trust domain,+`openshell.local`:++- `spire-server`, with `jwt_issuer = "http://spire-oidc:8008"` so every+ JWT-SVID names the issuer the mesh will trust.+- `spire-oidc`, the SPIRE OIDC Discovery Provider, publishing the trust+ domain's JWT keys at `http://spire-oidc:8008/.well-known/openid-configuration`+ on the Compose network. Plain HTTP is fine there; in production put it+ behind TLS.+- `spire-agent`, serving the Workload API on+ `/var/lib/openshell/spire-agent/agent.sock` and attesting callers with+ the `docker` workload attestor. It runs in the host PID namespace and reads+ the Docker socket so it can map a caller back to its container.++OpenShell labels every supervisor container with+`openshell.ai/sandbox-name=<name>`, so one registration entry per sandbox+gives it its own SPIFFE ID:++```bash+spire-server entry create \+ -parentID spiffe://openshell.local/host \+ -spiffeID spiffe://openshell.local/sandbox/demo \+ -selector docker:label:openshell.ai/sandbox-name:demo+```++`make sandbox NAME=demo` runs this before it creates the sandbox.++## 2. The mesh: trust SPIRE as a workload issuer++`agentmesh-one` starts with two extra flags:++```text+--workload-issuer=http://spire-oidc:8008+--allowed-audiences=agentmesh+```++A JWT-SVID from that issuer with `aud: agentmesh` is now a workload identity+the control plane accepts at `/token/exchange`, which is how the edge node+turns it into a Biscuit. The policy binds the sandbox identity to a role:++```json+{+ "roles": [+ { "name": "sandbox",+ "allowed_services": ["system://mesh.catalog", "mcp://calc"],+ "allowed_targets": ["*"] }+ ],+ "bindings": [+ { "role": "sandbox", "members": ["user:spiffe://openshell.local/sandbox/demo"] }+ ]+}+```++`system://mesh.catalog` lets the role list tools; `mcp://calc` lets it call+them. The office node publishes the same calculator twice, as `mcp://calc`+and `mcp://payroll`, so the policy has something to refuse.++Two nodes join with the standing join token: the `edge-node` beside the+sandboxes, whose API Compose publishes on `127.0.0.1:8090`, and the+`office-node`, which fronts the calculator. The edge node declares no+services; it is the sandboxes' door to the mesh.++## 3. OpenShell: one line and one profile++The gateway runs from `deploy/docker/docker-compose.yml` of the OpenShell+release, with one line added to `gateway.toml`:++```toml+[openshell.drivers.docker]+provider_spiffe_workload_api_socket = "/var/lib/openshell/spire-agent/agent.sock"+```++The gateway projects that socket into every sandbox supervisor it starts.+The supervisor runs on the host network, so the token endpoint below is the+edge node's published port on loopback, which is the form OpenShell accepts+for a plaintext token endpoint.++The provider profile declares the credential as a token grant and names the+endpoints it applies to:++```yaml+id: agentmesh+credentials:+ - name: mesh_token+ auth_style: bearer+ header_name: X-Mesh-Authentication+ token_grant:+ grant_type: client_credentials+ token_endpoint: http://127.0.0.1:8090/oauth/token+ jwt_svid_audience: agentmesh+ client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-spiffe+ cache_ttl_seconds: 60+endpoints:+ - host: host.openshell.internal+ port: 8090+ path: /mcp+ protocol: mcp+ enforcement: enforce+ mcp:+ allow_all_known_mcp_methods: true+ rules:+ - allow: {}+ - host: host.openshell.internal+ port: 8090+ path: /v1/**+ protocol: rest+ access: read-write+ enforcement: enforce+```++`jwt_svid_audience` is the `aud` the supervisor asks SPIRE for, and must be+one the control plane allows. `cache_ttl_seconds` is how long the supervisor+keeps a Biscuit before it trades a fresh SVID for a new one, so it is also+how long a policy change takes to reach a running sandbox. The `/mcp`+endpoint uses OpenShell's MCP inspection; the `/v1/**` endpoint is the+node's OpenAI-compatible API for models published on the mesh.++Register the gateway and the provider once:++```bash+openshell gateway add http://127.0.0.1:8080 --name openshell-agentmesh+openshell profile import -f openshell/provider-profile.yaml+openshell provider create --name agentmesh --type agentmesh --runtime-credentials+```++`--runtime-credentials` records that this provider stores nothing: the+credential is resolved at runtime, per sandbox. `make up` does all of this.++## 4. A sandbox on the mesh++```bash+make sandbox NAME=demo+```++creates the SPIRE entry, waits for the agent to pick it up, and runs++```bash+openshell sandbox create --name demo --from openshell-agentmesh-sandbox:local \+ --provider agentmesh --detach -- sleep infinity+```++The image is Ubuntu with `curl`; an agent image takes its place. Now call+the mesh from inside the sandbox:++```bash+make call NAME=demo+```++```text+== tools the mesh offers sandbox demo+ 12D3KooWNmsppgKL… mcp://calc/add Return a + b.+ 12D3KooWNmsppgKL… mcp://calc/multiply Return a * b.+== mcp://calc, allowed for the sandbox role+mcp://calc/add(2, 3) = 5.0+== mcp://payroll, not in the sandbox role+ (no tool of mcp://payroll is visible to this sandbox; calling the office node directly)+mcp://payroll/add(2, 3) -> refused: auth rejected by 12D3KooWNmsppgKL…: biscuit: denied by no matching policies+```++Each line is an `openshell sandbox exec … curl` against+`http://host.openshell.internal:8090/mcp` with no credential in the+request. `find_remote_tools` lists only what the policy allows the caller to+see, so `mcp://payroll` is absent; asking the office node for it by name is+refused there, by the office node, with the sandbox's own Biscuit as the+evidence. The control plane log shows the exchange that produced that+Biscuit:++```text+Border Crossing {"endpoint": "/token/exchange", "decision": "allow",+ "subject": "spiffe://openshell.local/sandbox/demo", "roles": ["sandbox"]}+```++## 5. Same image, same profile, different identity++```bash+make rogue+```++creates a second sandbox, `rogue`, with its own SPIRE entry but no binding in+the policy. Its supervisor gets a JWT-SVID and a Biscuit the same way, and+the Biscuit carries no roles:++```text+== tools the mesh offers sandbox rogue+== mcp://calc, allowed for the sandbox role+mcp://calc/add(2, 3) -> refused: the mesh shows this sandbox no MCP provider at all (no role binds its identity)+```++To let it in, add `user:spiffe://openshell.local/sandbox/rogue` to the+`sandbox` role's members in `policy.json` and push the policy:++```bash+make policy+make call NAME=rogue+```++The running sandbox is allowed within a minute, once the supervisor's cached+Biscuit expires and it exchanges a fresh SVID. Removing the member again+revokes the sandbox the same way. Neither step touches the sandbox, the+gateway, or any token.++## Using it with an agent++An agent in the sandbox sees the mesh as an ordinary MCP server at+`http://host.openshell.internal:8090/mcp` with no authentication, because+the supervisor adds it. Create the sandbox from your agent image with+`--provider agentmesh`, then register that URL with the agent's MCP client,+for example `claude mcp add --transport http mesh+http://host.openshell.internal:8090/mcp` for Claude Code. Models published+on the mesh are available the same way through+`http://host.openshell.internal:8090/v1`, the node's OpenAI-compatible API.++## What to change for a real deployment++- Register one SPIRE entry per sandbox from the system that creates the+ sandbox, as `make sandbox` does here, or bind on a broader selector such as+ `docker:label:openshell.ai/sandbox-namespace:<team>` and give the role to+ every sandbox in that namespace.+- Serve the OIDC discovery provider over TLS and point `--workload-issuer`+ at that URL; the `jwt_issuer` in `server.conf` must match it exactly.+- Keep the edge node on the gateway host. OpenShell accepts a plaintext+ token endpoint only on loopback or at a Kubernetes service name; anywhere+ else the node's API needs `--tls-cert` and `--tls-key` and the supervisor+ must trust that certificate.+- On Kubernetes, OpenShell's Helm chart mounts the SPIFFE CSI socket with+ `provider_spiffe_workload_api_socket_path`, and SPIRE's Kubernetes+ workload attestor replaces the Docker labels. The profile and the policy+ stay the same.++## Cleaning up++```bash+make down+```++removes the sandboxes, the provider and profile, the gateway registration,+and the Compose project. OpenShell's state under `/var/lib/openshell` stays.diff --git a/site/content/docs/preview/sandboxed-agents.md b/site/content/docs/preview/sandboxed-agents.mdindex ac56cb15..428253b0 100644--- a/site/content/docs/preview/sandboxed-agents.md+++ b/site/content/docs/preview/sandboxed-agents.md@@ -83,7 +83,9 @@ issuer with `--workload-issuer` and binds roles to the subject:The sandbox still holds nothing. What changes is that the mesh, not theorchestrator, decides what each sandbox identity may call, and revoking the-sandbox's role takes effect without touching the proxy.+sandbox's role takes effect without touching the proxy. The+[OpenShell sandboxes guide](../../guides/openshell/) runs this end to end on+one machine with SPIRE.## Blueprint 2: Docker Sandbox (`docker sbx`) & Kubernetes `agent-sandbox`