Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: fix the guides that fail as written
Tomas Tormo601d0e60012b
diff --git a/development/examples/code-reviewer-pool/manager/values.yaml b/development/examples/code-reviewer-pool/manager/values.yamlindex dfa3e5cc..08b507fa 100644--- a/development/examples/code-reviewer-pool/manager/values.yaml+++ b/development/examples/code-reviewer-pool/manager/values.yaml@@ -10,3 +10,10 @@ config:service:name: pool-managerimage: pool-manager:local+ # The manager calls its node's API with the token the chart generates.+ env:+ - name: AGENTMESH_API_TOKEN+ valueFrom:+ secretKeyRef:+ name: manager-agentmesh-node-api-token+ key: api-tokendiff --git a/site/content/docs/preview/_index.md b/site/content/docs/preview/_index.mdindex fa62793e..ef1b01bf 100644--- a/site/content/docs/preview/_index.md+++ b/site/content/docs/preview/_index.md@@ -17,8 +17,6 @@ you find.identity, and how an agent serves.- [Agent Mesh Connect](mobile/): the Android and iOS app that turns a phone into anode.-- [Scale report](scale-report/) and [how to reproduce it](scale-experiment/):- what a sandboxed agent costs, measured up to a thousand agents on one host.Everything outside this section (the node, the routers, the control plane,identity, policy and the deployment guides) is the stable core.diff --git a/site/content/docs/preview/sandboxed-agents.md b/site/content/docs/preview/sandboxed-agents.mdindex 1a0d40ab..28e4de56 100644--- a/site/content/docs/preview/sandboxed-agents.md+++ b/site/content/docs/preview/sandboxed-agents.md@@ -47,13 +47,12 @@ flowchart LR1. **Mint and seal a task token before starting the task:**The orchestrator calls `POST /oauth/token` on the local `agentmesh-node` with a`TaskAuthorizationRule` (and `seal=true`), receiving a **sealed Task- Biscuit** scoped to the single task:+ Biscuit** scoped to the single task. The request carries no+ `subject_token`, so the node narrows its own Biscuit:```bashTASK_TOKEN=$(curl -sS --unix-socket ~/.config/agentmesh/agentmesh.sock \http://localhost/oauth/token \-d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \- -d 'subject_token_type=urn:agentmesh:params:oauth:token-type:biscuit' \- -d "subject_token=$(jq -r .biscuit ~/.config/agentmesh/credential.json 2>/dev/null || true)" \-d 'seal=true' \--data-urlencode 'options={"name":"tasks/pr-review-42","rules":[{"allowed_services":["mcp://github","inference://*"],"operation":{"allowed_tools":["get_pull_request","list_PullRequest_files"]}}]}' \| jq -r .access_token)@@ -177,7 +176,7 @@ offline in memory using the TypeScript or Python SDK (or `POST /oauth/token` on```pythonfrom datetime import datetime, timedelta, timezonefrom google.protobuf.timestamp_pb2 import Timestamp-from agent_mesh import AgentMesh, agentmesh_pb2+from agent_mesh._proto import agentmesh_pb2# Hop 1: Orchestrator narrows its session to read-only BigQuery sales_2026# and two MCP tools for 15 minutes.@@ -237,36 +236,30 @@ hop2_session = hop1_session.attenuate(### Example: two-hop attenuation in TypeScript```typescript-import { create } from "@bufbuild/protobuf";import { timestampFromDate } from "@bufbuild/protobuf/wkt";-import { TaskAuthorizationRuleSchema } from "@agentmesh-p2p/sdk/gen/agentmesh_pb.ts";-const hop1 = session.attenuate(- create(TaskAuthorizationRuleSchema, {- name: "tasks/session-bq-read-sales",- expireTime: timestampFromDate(new Date(Date.now() + 15 * 60_000)),+const hop1 = await session.attenuate({+ name: "tasks/session-bq-read-sales",+ expireTime: timestampFromDate(new Date(Date.now() + 15 * 60_000)),+ rules: [+ {+ allowedServices: ["mcp://bigquery"],+ operation: { allowedTools: ["list_tables", "query_sales"] },+ },+ ],+});++const leafSession = await (+ await hop1.attenuate({+ name: "tasks/subagent-q1-only",rules: [{allowedServices: ["mcp://bigquery"],- operation: { allowedTools: ["list_tables", "query_sales"] },+ operation: { allowedTools: ["query_sales"] },},],- }),-);--const leafSession = hop1- .attenuate(- create(TaskAuthorizationRuleSchema, {- name: "tasks/subagent-q1-only",- rules: [- {- allowedServices: ["mcp://bigquery"],- operation: { allowedTools: ["query_sales"] },- },- ],- }),- )- .seal();+ })+).seal();```When `hop2_session` calls `egress://bigquery.googleapis.com`, the egressdiff --git a/site/content/docs/preview/scale-experiment.md b/site/content/docs/preview/scale-experiment.mddeleted file mode 100644index f4f47b08..00000000--- a/site/content/docs/preview/scale-experiment.md+++ /dev/null@@ -1,180 +0,0 @@-----title: "Scale experiment: reproducing the thousand-agent run"-linkTitle: "Scale experiment"-weight: 5-aliases:- - /docs/scale-experiment/------{{% alert title="Preview" color="warning" %}}-The scripts under `tests/scale/` and `scripts/` are research tooling for the-[scale report](../scale-report/). They are kept working but are not a-supported product surface.-{{% /alert %}}--The report says what was measured and what it means. This page says how to-run it again. The setup is one host, one `agentmesh-node`, and *N* agents. Each-agent is a Firecracker microVM with no network device, and its only way out-is a vsock to its own `agentmesh-box`. A thousand agents have been run on one-`n2-standard-64`.--| Component | Role |-|---|---|-| host VM | `n2-standard-64` on GCP with nested virtualisation; runs the node and one `agentmesh-box` per agent |-| guest | Firecracker microVM, Alpine, about 160 MiB, no network device |-| `nano-init` | PID 1 in the guest: builds `tun0`, carries its own TCP stack, keeps the mesh name on every flow |-| agent | the [example harness](https://github.com/google/agentmesh/tree/main/development/examples/agent-harness), holding no credentials |--## Prerequisites--- A guest kernel with `CONFIG_TUN=y`. The Firecracker quickstart, 5.10 and- 6.1 CI kernels do not have it. 6.18.41 does. `startup-script.sh` downloads- a TUN-capable kernel, and fails with a clear error instead of booting a- guest whose agent can never get a route.-- A bootstrap token at `/etc/agentmesh-bootstrap-token` on the host. The launcher- refuses to start without one.-- KVM, with `/dev/kvm` writable by the invoking user.--## 1. Build the guest image--Build once, locally, then upload:--```bash-./scripts/build-rootfs.sh gs://my-agentmesh-bucket/scale-test-```--The image holds Alpine, Python, `nano-init` and the example harness as an-ext4 filesystem. It uses the harness and not the chaos agent, because a-scale run needs the same request every time. To build a different agent-into the image, point `AGENT_SRC` at it and give it enough space. An image-that is too small fails during the copy and not at boot:--```bash-ROOTFS_MB=2048 AGENT_SRC=cmd/chaos-agent ./scripts/build-rootfs.sh-```--## 2. Provision the host--```bash-./scripts/provision-scale-vm.sh \- --prefix agentmesh-minions --count 1 \- --machine-type n2-standard-64 \- --local-binaries gs://my-agentmesh-bucket/scale-test \- --no-spot-```--This builds your local binaries and injects them with a `startup-script.sh`-that downloads everything on boot. Use `--no-spot` for anything you intend-to keep. Spot capacity for this machine type is limited, a reclaimed run-produces no result, and spot instances are terminated by host maintenance-while standard ones are live-migrated. On `ZONE_RESOURCE_POOL_EXHAUSTED`,-try another zone.--## 3. Size the guest--Run once per agent image:--```bash-sudo tests/scale/measure-guest.sh-```--A guest with too little memory fails in ways that look like network faults.-A guest with too much memory wastes the memory that limits the population.-For the harness: 136 MiB fails, 144 MiB runs slowly, 160 MiB runs at full-speed, against a working set of about 206 MiB.--## 4. Launch--```bash-gcloud compute ssh agentmesh-minions-1 --zone us-central1-c--sudo tests/scale/validate-launcher.sh # check that one works before asking for a thousand-sudo SANDBOX_LINGER=2400 /opt/microvm/launch-microvms.sh 1000-```--The launcher checks Firecracker, KVM, the kernel, the rootfs, the binaries-and the token. It then starts one `agentmesh-box` per agent and one microVM per-`agentmesh-box`, all against one node. The rootfs is shared read-only. A private-copy per agent would be half a terabyte at a thousand agents.--`SANDBOX_LINGER` keeps each sandbox open after its agent finishes. A density-measurement needs the whole population resident at the same time. By-default a sandbox powers off when it is done, so a thousand sandboxes-started in sequence are never a thousand at once. Zero is the right value-for real work.--| Variable | Meaning |-|---|---|-| `VM_MEM_MIB` | guest memory, default 160 |-| `SANDBOX_LINGER` | seconds to keep a sandbox after the agent exits, default 0 |-| `AGENTMESH_MODEL` | model to ask the mesh for; when unset, the first model in the catalog is used |-| `CONTROL_PLANE` | defaults to the `bananas` testnet |-| `AGENT_DOMAIN` | the domain under which agents are named |--These values reach the guest as kernel command-line pairs, which is the only-way to pass anything to PID 1, so they cannot contain spaces. The launcher-rejects values that do.--## 5. Collect--```bash-sudo tests/scale/collect-fleet.sh \- --node-socket /var/run/agentmesh-node.sock --duration 1500 --out fleet.jsonl-```--The headline number is how many agents the *node* is serving, and not how-many microVMs were started. A guest that booted and never reached its-boundary is a process, not an agent. The script asks the node and samples-over time, because the shape of the curve shows whether the population came-up smoothly. Watch `agentmesh_node_agents_untracked_total`. If it is not zero, the-agent count is a lower bound and not a measurement.--## 6. Drive load--```bash-sudo tests/scale/load-fleet.sh --agents 200 --requests 200 --out /var/log/load-sudo tests/scale/load-fleet.sh --report /var/log/load-```--Load goes through one boundary per agent, so the node sees *N* principals-and the admission path is exercised as in practice. One generator against-one boundary would measure a socket, not a mesh.--## Watching--```bash-sudo tail -f /var/log/startup-script.log # host setup-sudo tail -f /var/log/fc-vm-1.log # one guest's console, agent output included-sudo curl -s --unix-socket /var/run/agentmesh-node.sock http://localhost/metrics | grep agentmesh_node_agents_seen-```--## The boundary sweep--The other half of the report needs no cloud. It starts a real mesh on kind-and attaches boundaries to it:--```bash-./tests/scale/run-density.sh --steps 1,2,4,8,16,32,64 --requests 500-```--Results are written to `tests/scale/results/` with `environment.json`, the-raw per-step observations and a rendered `table.md`.--## Chaos testing--`cmd/chaos-agent` is a LangChain agent pointed at whatever tools the mesh-grants it and told to abuse them. It answers the question "does the mesh-survive an autonomous caller", and not "what does anything cost", because-it never issues the same request twice.--```bash-ROOTFS_MB=2048 AGENT_SRC=cmd/chaos-agent ./scripts/build-rootfs.sh--sudo AGENTMESH_MODEL=google/gemma-2-2b-it CHAOS_SLEEP=30 VM_MEM_MIB=512 \- /opt/microvm/launch-microvms.sh 25-```--It runs until stopped. It sleeps a random interval between rounds so that a-fleet does not arrive at the providers at the same time, and it treats its-own crashes as data. Like the harness, it holds no credentials and takes its-model from the catalog.diff --git a/site/content/docs/preview/scale-report.md b/site/content/docs/preview/scale-report.mddeleted file mode 100644index d157a63d..00000000--- a/site/content/docs/preview/scale-report.md+++ /dev/null@@ -1,293 +0,0 @@-----title: "Scale report: what an agent costs"-linkTitle: "Scale report"-weight: 4-aliases:- - /docs/scale-report/------{{% alert title="Preview" color="warning" %}}-These measurements are of the sandbox datapath described in-[Sandboxed agents](../sandboxed-agents/). They were recorded on 2026-08-21-at commit `e5b2966`, when the boundary spoke SOCKS5. The boundary has since-moved to HTTP `CONNECT` and has not been measured again. The shape of the-results is what matters. Single figures are indicative.-{{% /alert %}}--The design gives every agent its own boundary, which resolves names and-enforces policy on each flow. That sounds expensive. This page measures it.-The method is written down so that the result can be challenged, and a-script is provided so that it can be run again. There are two experiments: a-sweep of boundaries attached to one node, and a thousand agents in microVMs-on one host.--## Experiment 1: the boundary--### Questions--1. **Density**: what does the *N*th boundary cost in memory?-2. **Startup**: how long does it take from launching a sandbox until it can- call the mesh, and does that time grow with the population?-3. **Overhead**: how much latency does an agent pay for reaching the mesh- through a policy instead of a socket?-4. **Enforcement**: does policy hold under load, and what does a refusal- cost?--### Method--One real mesh (control plane, router, node) on a kind cluster, as in the-end-to-end suite. Boundaries were attached to the node one at a time, as-host processes and not as containers, because the question is what-`agentmesh-box` costs. A container would measure the container runtime.--The load generator, `agentmesh-bench`, issues the same request every time-(`GET /v1/models`) and enters the mesh in the same way an agent does,-through the boundary's socket. Each step of the sweep was measured in four-conditions:--| Condition | Isolates |-|---|---|-| baseline | the node answering over its own socket, with no boundary in the path |-| reused flow | what an agent normally experiences: one admitted flow, many requests |-| new flow per request | admission: the handshake and the policy decision paid every time |-| denied | enforcement, which leaves no latency behind and must be counted separately |--Client latency shows what an agent experienced. The counters on the servers-show what they did, including the flows they refused. Percentiles are-nearest-rank over the full sample, so every figure was observed. Failed-requests never enter the latency distribution. Warmup requests (20 per-condition) are reported separately, because a first call that pays for-discovery is a real cost.--Environment: Intel Xeon 2.60 GHz, 48 vCPU, 118 GiB, Linux 7.1.6, Go 1.26.5.-The sweep covered 1, 2, 4, 8, 16, 32 and 64 sandboxes, with 500 requests per-condition per step at concurrency 4.--### Results--Latency in milliseconds, memory in MB.--| sandboxes | reused p50 | reused p99 | new-flow p50 | new-flow p99 | admission (µs) | idle RSS | total RSS | denied | leaked |-|---|---|---|---|---|---|---|---|---|---|-| 1 | 1.36 | 2.30 | 1.55 | 78.15 | 19 | 20.2 | 0.02 GiB | 500 | 0 |-| 2 | 1.34 | 2.09 | 1.40 | 3.19 | 20 | 19.4 | 0.06 GiB | 500 | 0 |-| 4 | 1.33 | 2.92 | 1.44 | 3.90 | 19 | 19.0 | 0.12 GiB | 500 | 0 |-| 8 | 1.33 | 2.37 | 1.46 | 6.23 | 18 | 18.8 | 0.21 GiB | 500 | 0 |-| 16 | 1.39 | 3.37 | 1.44 | 2.38 | 19 | 18.9 | 0.39 GiB | 500 | 0 |-| 32 | 1.34 | 2.42 | 1.37 | 3.22 | 18 | 18.1 | 0.72 GiB | 500 | 0 |-| 64 | 1.30 | 1.80 | 1.41 | 4.62 | 18 | 17.4 | 1.37 GiB | 500 | 0 |-| *baseline* | *1.39* | *2.37* | | | | | | | |--Every allowed step served 500 of 500 requests. Every denied step served 0 of-500. "Admission" is the boundary's own mean time to classify a destination-and open it. "Leaked" counts requests that reached a destination that policy-forbade.--**Density.** A boundary settles at 17 to 20 MB resident once idle.-Sixty-four of them, with one under continuous load, came to 1.37 GiB. The-per-sandbox mean falls as the population grows because the same boundary-carries all the load at every step while the others sit idle. The marginal-cost of one more agent is the idle figure, not the mean.--**Startup.** Across 64 sandboxes: median 59 ms, min 58, p95 59, max 70,-where ready means that the socket accepts connections. The 64th sandbox-started as fast as the first.--**Overhead.** Baseline p50 was 1.39 ms. Through the boundary on a reused-flow, p50 ranged from 1.30 to 1.39 ms, at or below baseline at every-population size. The boundary did not make requests faster. Its end-to-end-overhead is smaller than the run-to-run variation of the measurement, so-this method cannot measure it. A fresh flow per request, which pays the-handshake and the policy decision each time, can be measured and is small:-p50 +9 to +157 µs over baseline. The boundary's own in-process-instrumentation put classifying and opening a destination at a mean of 18 to-20 µs, and this moved by less than 2 µs between one sandbox and sixty-four.--**Enforcement.** 3,500 attempts at forbidden destinations, zero successes, at-every population size. The boundary's counter agreed with the client's at-every step. Refusals ran at 24,000 to 28,000 per second, about ten times the-allowed rate, because a denied flow is decided from the name and never-dialled.--### Threats to validity--- One machine, one run, no confidence intervals. The overhead result in- particular is a case where a single figure could be over-interpreted.-- A trivial request. `/v1/models` is a small response from a warm node. It- isolates mesh overhead because it does almost no work, and for the same- reason it says nothing about large payloads or streaming.-- Load through one boundary while the rest sit idle. This answers "do the- others get in the way" and not "what happens when all *N* are busy".-- A reproducible tail anomaly. The single-sandbox, new-flow step showed p99- excursions of 60 to 80 ms in every run, and this did not happen at higher- populations. It is left in the record without an explanation.-- Host processes and not sandboxes. This measures the boundary and not the- isolation around it. A microVM per agent costs much more, and none of that- is counted here.--## Experiment 2: a thousand agents on one host--One `n2-standard-64`, one `agentmesh-node` enrolled in the public `bananas`-testnet, and a thousand agents. Each agent is a Firecracker microVM with no-network device, and it reaches the mesh through its own `agentmesh-box` over-vsock. The agent is the example harness: connect, discover tools, attempt a-model call, stop. Raw samples are in-[`tests/scale/results/fleet-1k`](https://github.com/google/agentmesh/tree/main/tests/scale/results/fleet-1k).--### Cost--| | total | per agent |-|---|---|---|-| guest microVMs | 162.7 GiB | **167 MiB** |-| boundaries (`agentmesh-box`) | 24.6 GiB | **25 MiB** |-| node (one, for all) | 386 MiB | 0.4 MiB |-| **together** | **187 GiB of 251 GiB** | **192 MiB** |--The node figure is the one that matters for the design. One `agentmesh-node`-served a thousand distinct agent principals in 386 MB, because an agent is-not a peer. It has no enrollment, no key and no place in the DHT. The mesh-gained a thousand principals and no members.--### Startup--A thousand sandboxes launched in 149 seconds, 6.7 per second, with a median-of 153 ms each and a p95 of 245 ms. The population became reachable as fast-as it was started:--| elapsed | agents serving | microVMs | guest memory |-|---|---|---|---|-| 0 s | 71 | 120 | 17.2 GiB |-| 44 s | 328 | 383 | 62.1 GiB |-| 99 s | 691 | 734 | 119.7 GiB |-| 160 s | **1000** | 1000 | 162.7 GiB |-| 323 s | 1000 | 1000 | 162.7 GiB |--Agents trail microVMs by a few seconds and never by more than about fifty.-That gap is a guest booting and resolving its first mesh name, and not a-queue forming. `agentmesh_node_agents_untracked_total` was 0, so the thousand is a-count and not a limit.--### Throughput--With the thousand agents resident, load was driven through 200 of them at-once, each through its own boundary, so the node saw 200 principals and not-200 connections from one client. Each agent sent 200 requests, with two in-flight at a time.--40,000 requests, none failed, in 0.43 s. That is an aggregate of roughly-92,000 requests per second while the other 800 sandboxes sat resident. Per-agent, the median was 534 req/s (min 490, max 652), so no principal was-starved. Client time to first byte: median 2.0 ms, p95 13 ms, p99 21 ms,-worst 98 ms.--This is an upper bound on what the enforcement path permits. It is not a-throughput claim for a deployed workload. The request was answered by the-node itself, so no upstream provider was in the path. The generator entered-at the boundary's socket and not from inside a guest, so the in-guest stack-and the vsock hop are not counted.--The node's own histogram of the 41,000 server-side durations (including-warmup):--| server-side duration | requests | share |-|---|---|---|-| under 0.5 ms | 35,580 | 86.8% |-| under 5 ms | 39,412 | 96.1% |-| under 10 ms | 40,207 | 98.1% |-| under 25 ms | 40,586 | 99.0% |-| 5 to 10 s | 400 | 1.0% |--The last row is not jitter. Those 400 requests took almost exactly 5.04 s-each, which is the node's DHT lookup timeout. `/v1/models` resolves providers-through the DHT. The walk found four peers, but it asks for up to twenty and-has no way to know that four is all there are, so it waited for the full-timeout and then cached the answer for thirty seconds. The cost is one slow-lookup per cache expiry, paid by whoever arrives on a cold cache. Everything-behind the cache is in the sub-millisecond rows above. It is still a real-problem: the two hundred callers who arrived together each paid the lookup-instead of sharing one.--### What an agent gets--Separately, one sandbox was booted and asked what the mesh would give it. The-sandbox was a microVM with no network device, no API key, no model endpoint-and no tool server address. It had only `mesh.alt` to ask.--| | |-|---|---|-| tools | 15, discovered over MCP with their JSON schemas |-| models | `google/gemma-2-2b-it` (a vLLM instance on a TPU elsewhere in the mesh) and `openrouter/auto` (routed outward) |-| credentials in the sandbox | none |-| network devices in the sandbox | none |--Both models answered. A LangChain agent then ran inside the sandbox, took-its model name from the catalog, and produced output from the TPU-hosted-model, using the stock OpenAI and MCP clients without changes. This shows-that the mesh is reachable. It says nothing about how well a 2B model drives-a fifteen-tool loop.--### Threats to validity--- One host, one run.-- The agents are the example harness. A heavier agent needs more guest- memory, and 167 MiB describes this workload only.-- Memory was measured with the population idle. Throughput came from a- separate pass over the same resident fleet.-- Load was driven from the host into each boundary's socket, which skips the- in-guest stack and the vsock hop. The real per-agent limit is lower.-- Only 200 of the thousand agents sent traffic.-- Inference was not exercised in the thousand-agent run. The agents asked for- a model named `default`, which no catalog contains, and 998 of those calls- returned `404`. The inference path is the separate demonstration above.-- A thousand is what fit comfortably in 251 GiB with this agent. Nothing here- found a limit.-- Spot instances were preempted twice during measurement before this run.- The final run used a standard instance.--## Conclusions--An agent costs about 192 MiB and 150 ms, and nearly all of that is the-microVM. The boundary is 25 MB of it, and the node's share is under half a-megabyte. The number of agents a host can run is decided by how much memory-the agents want.--The mesh does not grow when the agent population grows. A thousand agents-arrived as one member with one enrollment. This is the reason the principal-is separated from the peer.--Enforcement is not a latency problem. It takes 18 to 20 µs to classify and-open a flow, and the end-to-end cost is too small for this method to-separate from noise. Checking every flow does not have to be traded against-performance, which removes the usual reason for such checks being disabled.--Nothing degraded across the ranges tested, and there were no failures where-success was expected and no successes where it was not.--## Reproducing--[Scale experiment](../scale-experiment/) has the step-by-step procedure. In-short:--```bash-# Experiment 1: docker and kind; stands up a real mesh-./tests/scale/run-density.sh --steps 1,2,4,8,16,32,64 --requests 500--# Experiment 2: a host with KVM, a TUN-capable guest kernel, a bootstrap token-./scripts/provision-scale-vm.sh --no-spot --local-binaries gs://your-bucket/agentmesh-# then on the host-SANDBOX_LINGER=2400 /opt/microvm/launch-microvms.sh 1000-/opt/microvm/collect-fleet.sh --node-socket /var/run/agentmesh-node.sock --duration 1500-```--Results land in `tests/scale/results/` with `environment.json`, the raw-observations and a rendered `table.md`. Single measurements by hand:--```bash-# through a boundary, as an agent would-agentmesh-bench run --socket /run/agent.sock --target http://mesh.alt/v1/models \- --requests 500 --concurrency 4 --scrape http://127.0.0.1:9600/metrics--# the same request with no boundary, for the baseline-agentmesh-bench run --target-unix /run/node.sock --target http://localhost/v1/models \- --requests 500 --concurrency 4-```diff --git a/site/content/docs/use-cases/multi-tier-guardrails.md b/site/content/docs/use-cases/multi-tier-guardrails.mdindex 65725f1b..3425186b 100644--- a/site/content/docs/use-cases/multi-tier-guardrails.md+++ b/site/content/docs/use-cases/multi-tier-guardrails.md@@ -31,7 +31,7 @@ The runnable example in [`development/examples/multi-tier-guardrails/`](https://| :--- | :--- | :--- || **1. Agent Developer (Alice)** | Onboarding & iterating on `a2a://support.acme` (`support_agent.py`) | Enrolls `agentmesh-node` in `env=staging` quarantine; zero code changes to promote to `env=prod` || **2. Platform / Networking** | Service discovery, outbound floor & replica lifecycle | Input-node `egress.require_labels: {env: prod}`, logical URI `a2a://support.acme`, and `contextId` continuity from Laptop (`v1`) to Cloud Run (`v2`) |-| **3. Central Security (CISO)** | Org-wide baseline RBAC, Quality Gate & Secret Brokering | Control-plane `policy.json` (`allowed_labels`, HTTP method/path rules on `egress://api.github.com`, `secret_ref: github-ro`) |+| **3. Central Security (CISO)** | Org-wide baseline RBAC, Quality Gate & Secret Brokering | Control-plane `policy.json` (`allowed_labels`, HTTP method/path rules on `egress://api.github.com`, `credential: github-ro`) || **4. Department Lead & End-User** | Local team gate + per-task tool narrowing | Egress-node `attenuation` (`check if label("team", "support");`) + RFC 8693 `/oauth/token` minting a sealed Task Biscuit (`tar_block`) || **5. Day-2 Operations (SRE)** | Real-time audit correlation & incident response | Structured `ALLOW`/`DENY` audit stream (`audit.py`) + instant mesh-wide revocation (`agentmesh-one admin ban`) |@@ -108,7 +108,7 @@ Effective Permission = (Layer 1: Central Security Block 0 Policy)```#### Layer 1 — Central Security (Org Baseline & Secret Broker)-In `policy.json`, Central Security assigns `egress://api.github.com` (`https://api.github.com`) to nodes labelled `team=support` with `secret_ref: "github-ro"`, and restricts callers to `GET /repos/google/agentmesh/pulls*`:+In `policy.json`, Central Security assigns `egress://api.github.com` (`https://api.github.com`) to nodes labelled `site=office` with `credential: "github-ro"`, and restricts callers to `GET /repos/google/agentmesh/pulls*`:* `GET /repos/google/agentmesh/pulls?state=open&per_page=1` $\rightarrow$ **`200 OK`** (the hosting node injects the read-only GitHub token from `secrets/github-ro`; the caller never holds the credential).* `POST /repos/google/agentmesh/pulls` $\rightarrow$ **`403 Forbidden`** (blocked by the Block 0 HTTP rule before GitHub ever receives the request).