Skip to content

Agent Mesh

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/.gitignore
new file mode 100644
index 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/Makefile
new file mode 100644
index 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.md
new file mode 100644
index 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.yaml
new file mode 100644
index 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.py
new file mode 100755
index 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.yaml
new file mode 100644
index 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.toml
new file mode 100644
index 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.yaml
new file mode 100644
index 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.json
new file mode 100644
index 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/Dockerfile
new file mode 100644
index 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:sandbox
diff --git a/development/examples/openshell-sandbox/spire/agent.conf.in b/development/examples/openshell-sandbox/spire/agent.conf.in
new file mode 100644
index 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.conf
new file mode 100644
index 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.conf
new file mode 100644
index 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.md
index 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.md
new file mode 100644
index 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.md
index 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 the
orchestrator, 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`