Skip to content

Agent Mesh

docs: the canonical way to run an agent

Antonio Ojeaeb7becfe4fb7
diff --git a/development/examples/agent-harness/Dockerfile b/development/examples/agent-harness/Dockerfile
new file mode 100644
index 00000000..03bd9a3d
--- /dev/null
+++ b/development/examples/agent-harness/Dockerfile
@@ -0,0 +1,31 @@
+# A sandbox image holds the harness and the plumbing that gives it a route.
+# No credentials, and no proxy configuration: the agent is unmodified and does
+# not know it is confined.
+FROM python:3.12-slim
+
+# socat bridges the boundary's Unix socket to a port, iproute2 builds the tun,
+# and tun2proxy makes that tun the way out. This is the same arrangement a
+# microVM runs, which is the point: the agent above it is identical either way.
+ARG TUN2PROXY_VERSION=v0.8.3
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends socat iproute2 ca-certificates curl unzip \
+ && curl -sSL -o /tmp/tun2proxy.zip \
+ "https://github.com/tun2proxy/tun2proxy/releases/download/${TUN2PROXY_VERSION}/tun2proxy-x86_64-unknown-linux-musl.zip" \
+ && unzip -j /tmp/tun2proxy.zip tun2proxy-bin -d /usr/local/bin \
+ && mv /usr/local/bin/tun2proxy-bin /usr/local/bin/tun2proxy \
+ && chmod +x /usr/local/bin/tun2proxy \
+ && apt-get purge -y curl unzip && apt-get autoremove -y \
+ && rm -rf /var/lib/apt/lists/* /tmp/tun2proxy.zip
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY agent.py entrypoint.sh ./
+RUN chmod +x entrypoint.sh
+
+# Building the tun needs NET_ADMIN, so this stays root. The isolation that
+# matters is the sandbox around the container, not the uid inside it; a
+# microVM makes the same trade with its own kernel.
+ENTRYPOINT ["./entrypoint.sh"]
diff --git a/development/examples/agent-harness/README.md b/development/examples/agent-harness/README.md
new file mode 100644
index 00000000..779a3ad6
--- /dev/null
+++ b/development/examples/agent-harness/README.md
@@ -0,0 +1,70 @@
+# Agent harness
+
+The canonical shape of an agent on SAM: about a hundred lines that hold the
+conversation and the tool loop, and nothing else. No model endpoint to
+configure, no API key, no tool servers deployed alongside it, and no network
+beyond what its policy names.
+
+Full walkthrough: [Running agents on SAM](https://sam-mesh.dev/docs/user/running-agents/).
+
+## What it demonstrates
+
+- **No credentials in the sandbox.** The gateway outside authenticates this
+ agent to the mesh. There is no key in this directory, its environment, or the
+ image built from it.
+- **Services addressed by name.** `mesh.sam.alt` is not in DNS and has no route
+ to it. The boundary resolves it and chooses a provider by policy, so the agent
+ never learns where anything runs.
+- **An ordinary HTTP client.** The OpenAI SDK and the MCP SDK, used as they
+ would be anywhere. Nothing here is SAM-specific, because an agent that needed
+ a special client could not be moved onto the mesh without rewriting it.
+
+## Files
+
+| | |
+| --- | --- |
+| `agent.py` | The harness. Discovers tools, calls a model, runs the loop. |
+| `entrypoint.sh` | The sandbox's route: a tun that leads to the boundary and nowhere else. |
+| `bundle.yaml` | Who this agent is and what it may reach. Read by `sam-box`, outside the sandbox. |
+| `Dockerfile` | The sandbox image: the harness and the plumbing that gives it a route. |
+
+## Running it
+
+With a `sam-node` already enrolled and serving its API on a socket:
+
+```bash
+# A boundary for this agent. Verification is on by default; the insecure flag
+# is for local experiments and says what it costs: whoever can write the
+# bundle decides which agent this sandbox is.
+sam-box run \
+ --socket /run/sam/agent.sock \
+ --sidecar-socket /run/sam/node.sock \
+ --bundle ./bundle.yaml \
+ --insecure-unverified-bundle \
+ --metrics-addr 127.0.0.1:9600
+
+# The sandbox. --network none is the assertion, not just the arrangement:
+# if this worked because the container could route somewhere, it would be
+# proving nothing. NET_ADMIN and /dev/net/tun are needed to build the tun that
+# becomes the only route out.
+docker build -t agent-harness .
+docker run --rm \
+ --network none \
+ --cap-add NET_ADMIN \
+ --device /dev/net/tun \
+ -v /run/sam/agent.sock:/run/agent.sock \
+ agent-harness "What tools do I have, and what can each one do?"
+```
+
+Notice what is *not* passed: no API key, no mesh token, no proxy variable, no
+endpoint. The agent asks for `mesh.sam.alt` and the sandbox has exactly one
+route, which leads to the boundary.
+
+## Seeing what it did
+
+```bash
+curl -s http://127.0.0.1:9600/metrics | grep sam_box_flows_total
+```
+
+Every flow the agent opened, by route class and outcome, including refusals.
+A refused flow never becomes a latency, so counting is the only way to see it.
diff --git a/development/examples/agent-harness/agent.py b/development/examples/agent-harness/agent.py
new file mode 100644
index 00000000..459adfea
--- /dev/null
+++ b/development/examples/agent-harness/agent.py
@@ -0,0 +1,153 @@
+"""A minimal agent harness that owns nothing but its own logic.
+
+This is the whole point of running an agent on SAM, in one file: there is no
+model endpoint to configure, no API key to mount, no tool server to deploy
+alongside it, and no network to lock down afterwards. The harness asks the mesh
+for a model and for tools, and the mesh decides what this particular agent is
+allowed to have.
+
+Three things are worth noticing while reading it.
+
+It holds no credentials. There is no key in this file, in its environment, or
+in the sandbox it runs in. The gateway outside the sandbox knows which agent
+this is and says so on every request; an agent that could assert its own
+identity could borrow somebody else's.
+
+It addresses services by name, not by address. `mesh.sam.alt` is not in DNS and
+has no route to it. The name is resolved by the boundary, which picks a
+provider according to policy, so the agent never learns where anything runs and
+cannot be pinned to a host that later moves.
+
+It is an ordinary HTTP client. Nothing here is SAM-specific: the OpenAI SDK and
+the MCP SDK are used exactly as they would be anywhere. That is deliberate. If
+running on the mesh required a special client, every existing agent would need
+rewriting to move onto it.
+"""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from openai import AsyncOpenAI
+
+# The mesh's own name for itself. Not DNS, not routable, and deliberately not
+# configurable: an agent that can be pointed somewhere else is one misconfigured
+# environment variable away from talking to something nobody authorised.
+MESH = "http://mesh.sam.alt"
+
+SYSTEM_PROMPT = """You are an agent running on a Sovereign Agent Mesh.
+
+You have tools available to you that were granted by mesh policy. Use them when
+they help. If a tool is refused, that is policy, not a bug: say so and continue
+without it rather than retrying.
+
+Answer the user's task directly and stop when it is done."""
+
+
+async def discover_tools(session):
+ """Ask the mesh what this agent is allowed to use.
+
+ The list is not fixed at build time and is not the same for every agent:
+ two agents on the same node can see different tools, because the mesh
+ answers according to who is asking.
+ """
+ listed = await session.list_tools()
+ tools = []
+ for tool in listed.tools:
+ tools.append(
+ {
+ "type": "function",
+ "function": {
+ "name": tool.name,
+ "description": tool.description or "",
+ "parameters": tool.inputSchema
+ or {"type": "object", "properties": {}},
+ },
+ }
+ )
+ return tools
+
+
+async def call_tool(session, name, arguments):
+ """Run one tool call, turning a refusal into an answer the model can use.
+
+ A denied tool must come back as text the model can reason about. Raising
+ here would end the run, which would turn "you may not do that" into a
+ crash and teach the model nothing.
+ """
+ try:
+ result = await session.call_tool(name, arguments=arguments)
+ return "".join(
+ block.text for block in result.content if hasattr(block, "text")
+ ) or str(result.content)
+ except Exception as exc: # noqa: BLE001 - any failure is a result to reason about
+ return f"tool call failed: {exc}"
+
+
+async def run(task, model, max_steps):
+ # No api_key that means anything: the gateway authenticates this agent to
+ # the mesh. The SDK requires the argument, so it gets a placeholder.
+ client = AsyncOpenAI(base_url=f"{MESH}/v1", api_key="unused")
+
+ async with sse_client(f"{MESH}/mcp") as (read, write):
+ async with ClientSession(read, write) as session:
+ await session.initialize()
+
+ tools = await discover_tools(session)
+ print(f"mesh granted {len(tools)} tools: "
+ f"{', '.join(t['function']['name'] for t in tools) or 'none'}",
+ file=sys.stderr)
+
+ messages = [
+ {"role": "system", "content": SYSTEM_PROMPT},
+ {"role": "user", "content": task},
+ ]
+
+ for step in range(max_steps):
+ response = await client.chat.completions.create(
+ model=model,
+ messages=messages,
+ tools=tools or None,
+ )
+ choice = response.choices[0].message
+ messages.append(choice.model_dump(exclude_none=True))
+
+ if not choice.tool_calls:
+ return choice.content or ""
+
+ for call in choice.tool_calls:
+ arguments = json.loads(call.function.arguments or "{}")
+ print(f"step {step + 1}: {call.function.name}({arguments})",
+ file=sys.stderr)
+ output = await call_tool(session, call.function.name, arguments)
+ messages.append(
+ {
+ "role": "tool",
+ "tool_call_id": call.id,
+ "content": output,
+ }
+ )
+
+ return "stopped: reached the step limit without finishing"
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("task", help="What the agent should do")
+ parser.add_argument(
+ "--model",
+ default=os.environ.get("SAM_MODEL", "default"),
+ help="Model to ask the mesh for; the mesh chooses the provider",
+ )
+ parser.add_argument("--max-steps", type=int, default=10)
+ args = parser.parse_args()
+
+ print(asyncio.run(run(args.task, args.model, args.max_steps)))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/development/examples/agent-harness/bundle.yaml b/development/examples/agent-harness/bundle.yaml
new file mode 100644
index 00000000..9d2f6d90
--- /dev/null
+++ b/development/examples/agent-harness/bundle.yaml
@@ -0,0 +1,27 @@
+# The agent bundle: who this agent is, and what it may reach.
+#
+# The bundle is read by sam-box, outside the sandbox. The agent never sees it
+# and cannot change it, which is the point: an agent that could edit its own
+# policy would not be constrained by one.
+version: v1
+
+agent:
+ # The mesh identity of this agent. Dot-separated and hierarchical, because
+ # policy matches on label boundaries: a rule for `*.prod.acme.example` admits
+ # this agent, and `evil-prod.acme.example` is not a match for it.
+ id: researcher-1.prod.acme.example
+
+ # The platform identity this claim is checked against. sam-box verifies a
+ # credential from the issuer names in --credential-issuer and only accepts
+ # the bundle if the credential's subject is this value, so writing the file
+ # is not enough to become this agent.
+ external_id: system:serviceaccount:agents:researcher
+
+egress:
+ # Everything not listed is refused, including DNS, because the sandbox has no
+ # resolver and the boundary answers by name. An empty list means the agent
+ # reaches the mesh and nothing else, which is the right default for an agent
+ # whose work is entirely tools and inference.
+ allow:
+ - api.github.com
+ - "*.githubusercontent.com"
diff --git a/development/examples/agent-harness/entrypoint.sh b/development/examples/agent-harness/entrypoint.sh
new file mode 100755
index 00000000..ae58421b
--- /dev/null
+++ b/development/examples/agent-harness/entrypoint.sh
@@ -0,0 +1,49 @@
+#!/bin/sh
+# The sandbox's network, such as it is.
+#
+# This does the same job as the microVM's init: give the sandbox one route,
+# leading to the boundary, and then leave the agent alone. In particular it
+# sets no proxy variables. An agent that has to be told where its proxy is has
+# to cooperate with its own confinement, and the next library that ignores the
+# convention, or the next subprocess that clears the environment, is outside
+# it. Here the agent is unmodified and its traffic leaves through tun0 because
+# there is nowhere else for it to go.
+set -eu
+
+BOUNDARY_SOCKET="${BOUNDARY_SOCKET:-/run/agent.sock}"
+
+if [ ! -S "${BOUNDARY_SOCKET}" ]; then
+ echo "no boundary socket at ${BOUNDARY_SOCKET}: this sandbox has no way out" >&2
+ exit 1
+fi
+
+# HTTP clients and tun2proxy both want a host:port; the boundary is a Unix
+# socket. socat is plumbing only: it decides nothing, and every byte still
+# arrives at the same socket for the boundary to rule on.
+socat TCP-LISTEN:1080,bind=127.0.0.1,fork,reuseaddr "UNIX-CONNECT:${BOUNDARY_SOCKET}" &
+
+# Everything the sandbox is given an address for is link-local, because that is
+# what these addresses are: RFC 3927 describes a single link with no router,
+# which is exactly what a tun to the boundary is. Nothing here is routable, and
+# nothing here can be confused with a real destination — a sandbox numbered out
+# of 10.0.0.0/8 would eventually be deployed somewhere that already uses it.
+ip tuntap add dev tun0 mode tun
+ip link set dev tun0 up
+ip addr add 169.254.1.1/30 dev tun0
+ip route add default dev tun0
+
+# The resolver address is a fiction that never receives a packet: virtual DNS
+# answers in tun2proxy and hands the name to the boundary. That is the point —
+# mesh.sam.alt has no address, and the boundary is what turns a name into a
+# provider.
+echo "nameserver 169.254.1.53" > /etc/resolv.conf
+
+tun2proxy --tun tun0 --proxy socks5://127.0.0.1:1080 --dns virtual \
+ --dns-addr 169.254.1.53 --virtual-dns-pool 169.254.64.0/18 &
+
+for _ in $(seq 1 100); do
+ ip route show default | grep -q tun0 && break
+ sleep 0.05
+done
+
+exec python agent.py "$@"
diff --git a/development/examples/agent-harness/requirements.txt b/development/examples/agent-harness/requirements.txt
new file mode 100644
index 00000000..bbf20ca7
--- /dev/null
+++ b/development/examples/agent-harness/requirements.txt
@@ -0,0 +1,9 @@
+# The harness needs a model client and a tool client. It does not need a SAM
+# client, because there is no such thing: the mesh is reached with ordinary
+# HTTP to an ordinary name.
+#
+# There is no SOCKS support here on purpose. The sandbox routes the agent's
+# traffic to the boundary through tun0, so the agent neither configures a proxy
+# nor knows there is one.
+openai>=1.40
+mcp>=1.2
diff --git a/scripts/microvm-init.sh b/scripts/microvm-init.sh
index 2c70cd80..d0ec90f2 100644
--- a/scripts/microvm-init.sh
+++ b/scripts/microvm-init.sh
@@ -1,30 +1,70 @@
#!/bin/sh
+# PID 1 in an agent sandbox.
+#
+# Its whole job is to give the guest a default route that leads to the sandbox
+# boundary, and then get out of the way. What it deliberately does not do is
+# reach into the agent: no proxy variables in its environment, no resolver
+# rewritten under it, nothing preloaded into its address space. An agent that
+# has to cooperate with its own confinement is not confined, because the next
+# library that ignores the convention, or the next subprocess that clears the
+# environment, is outside it.
+#
+# So the agent below is unmodified. It makes ordinary requests to ordinary
+# names, and every one of them leaves through tun0 because there is nowhere
+# else for them to go.
+set -eu
+
mount -t proc proc /proc
mount -t sysfs sysfs /sys
mount -t devtmpfs devtmpfs /dev
-# Setup localhost
ip link set dev lo up
-# 1. Bridge local TCP to Host VSOCK (Firecracker CID 2 maps to host UDS)
-# The host sam-box UDS will receive connections from this port
-socat TCP-LISTEN:8080,fork,reuseaddr VSOCK-CONNECT:2:8080 &
+# The boundary is a Unix socket on the host. Firecracker's vsock multiplexes
+# guest connections onto "<uds_path>_<port>", so a connection to CID 2 port
+# 1080 arrives on the host at the path sam-box serves. socat is only plumbing:
+# it decides nothing and sees nothing the boundary would not.
+socat TCP-LISTEN:1080,bind=127.0.0.1,fork,reuseaddr VSOCK-CONNECT:2:1080 &
-# 2. Setup transparent network using tun2proxy
+# One interface, one route, and it leads to the boundary. There is no NIC in
+# this guest, so this is not the preferred way out; it is the only one.
+#
+# Every address here is link-local, because that is what these addresses are
+# for: RFC 3927 describes a single link with no router, which is exactly what a
+# tun to the boundary is. Nothing is routable and nothing can be mistaken for a
+# real destination — a sandbox numbered out of 10.0.0.0/8 would eventually be
+# deployed somewhere that already uses it.
ip tuntap add dev tun0 mode tun
ip link set dev tun0 up
-ip addr add 198.18.0.1/15 dev tun0
-ip route add default via 198.18.0.1 dev tun0
+ip addr add 169.254.1.1/30 dev tun0
+ip route add default dev tun0
+
+# The resolver address is a fiction that never receives a packet: virtual DNS
+# answers inside tun2proxy and hands the name to the boundary instead. That is
+# the point — mesh.sam.alt has no address of its own, and the boundary is what
+# turns the name into a provider.
+echo "nameserver 169.254.1.53" > /etc/resolv.conf
+
+# socks5, because that is what sam-box speaks. The previous version of this
+# script said http, which the boundary has never spoken, and then had the agent
+# call the bridge directly, which went around the tun it had just built.
+tun2proxy --tun tun0 --proxy socks5://127.0.0.1:1080 --dns virtual \
+ --dns-addr 169.254.1.53 --virtual-dns-pool 169.254.64.0/18 &
-# tun2proxy will catch all traffic on tun0 and forward to the socat TCP port (which goes to sam-box on host)
-tun2proxy --tun tun0 --proxy http://127.0.0.1:8080 &
+# Wait for the route to exist, so the agent's first request fails for real
+# reasons rather than for being early.
+for _ in $(seq 1 100); do
+ [ -d /sys/class/net/tun0 ] && break
+ sleep 0.05
+done
-# Give network a second to settle
-sleep 2
+echo "Sandbox ready; starting agent." > /dev/console
-echo "Starting Chaos Agent Loop..."
-cd /app/chaos-agent
-python3 agent.py --mcp-url http://127.0.0.1:8080/mcp --inference-url http://127.0.0.1:8080/v1 > /dev/console 2>&1
+# The agent is given a task and nothing else. It reaches the mesh by name,
+# holds no credentials, and does not know it is in a virtual machine.
+cd /app/agent
+python3 agent.py "${AGENT_TASK:-Describe the tools you have and what each is for.}" \
+ > /dev/console 2>&1 || echo "agent exited non-zero" > /dev/console
-echo "Agent completed. Powering off." > /dev/console
+echo "Agent finished. Powering off." > /dev/console
reboot -f
diff --git a/site/content/docs/user/running-agents.md b/site/content/docs/user/running-agents.md
new file mode 100644
index 00000000..554a1a0e
--- /dev/null
+++ b/site/content/docs/user/running-agents.md
@@ -0,0 +1,285 @@
+---
+title: "Running agents on SAM"
+description: "The canonical way to deploy an agent: ship the harness, let the mesh provide the model, the tools and the network"
+weight: 15
+---
+
+## What you actually deploy
+
+An agent is usually three things bolted together: some logic that decides what
+to do next, a model that does the thinking, and a set of tools it can act
+with. Deploying one normally means deploying all three, plus the credentials
+for the model, plus network access broad enough for the tools to work — which
+in practice means the agent can reach the whole internet, because nobody knows
+in advance which addresses it will need.
+
+On SAM you deploy **only the first one**. The mesh provides the other two, and
+the network the agent gets is exactly the network its policy describes.
+
+The piece you write and ship is the **harness**: the loop that holds the
+conversation, decides when to call a tool, and knows when the work is done.
+Everything else is asked for by name at runtime.
+
+| | Who provides it | How the agent asks |
+| --- | --- | --- |
+| **Harness** | You. This is your code. | — |
+| **Inference** | The mesh, from whichever peer policy allows | `http://mesh.sam.alt/v1` |
+| **Tools (MCP)** | The mesh, local and remote peers alike | `http://mesh.sam.alt/mcp` |
+| **Network** | The boundary, per flow, by name | ordinary HTTP to allowed names |
+
+The consequence worth pausing on: **the harness holds no credentials**. There
+is no model API key in the sandbox, no mesh token, no service account file.
+This is not a convenience. An agent that holds a key can leak a key, and an
+agent that can be prompt-injected into leaking one will eventually be.
+
+## The three concepts
+
+### Inference is a name, not an endpoint
+
+The agent asks `mesh.sam.alt` for a model. It does not know which peer answers,
+and it cannot find out. Policy decides which providers this agent may use, and
+the mesh picks among them.
+
+```python
+client = AsyncOpenAI(base_url="http://mesh.sam.alt/v1", api_key="unused")
+```
+
+That is an ordinary OpenAI SDK client. Nothing about it is SAM-specific, which
+matters: if running on the mesh required a bespoke client, every existing agent
+would have to be rewritten to move onto it.
+
+The `api_key` is a placeholder because the SDK insists on one. The real
+authentication happens outside the sandbox, where the agent cannot reach it.
+
+### Tools arrive over MCP, and the list is per-agent
+
+The same name serves tools:
+
+```python
+async with sse_client("http://mesh.sam.alt/mcp") as (read, write):
+ async with ClientSession(read, write) as session:
+ await session.initialize()
+ tools = await session.list_tools()
+```
+
+Two agents on the same node can list different tools, because the mesh answers
+according to who is asking. Tools hosted by other peers appear alongside local
+ones and are called identically — the agent cannot tell, and does not need to.
+
+A refused tool call comes back as an error the model can read, not a crash. A
+denial is information the agent should reason about, not an outage.
+
+### The boundary is the only way out
+
+The sandbox has no network interface, no DNS resolver and no route. It has a
+single Unix socket, on which `sam-box` speaks SOCKS5.
+
+Every connection the agent opens arrives there as a **name**, and the boundary
+decides what it is:
+
+- `mesh.sam.alt` — the mesh's own surface: inference and tools.
+- `<service>.mcp.sam.alt` — a specific mesh service, provider chosen by discovery.
+- anything else — matched against the agent's egress allowance, and refused if absent.
+
+Because the destination arrives as a name rather than an address, policy can be
+written about `api.github.com` rather than about whatever IP that resolves to
+this week. And because the sandbox has no other route, a refusal is not a
+speed bump the agent can route around — there is nothing to route around it
+with.
+
+### Identity is asserted about the agent, never by it
+
+`sam-box` reads a **bundle** that names the agent and describes what it may
+reach. The bundle lives outside the sandbox. The agent never sees it and cannot
+change it.
+
+```yaml
+version: v1
+agent:
+ id: researcher-1.prod.acme.example
+ external_id: system:serviceaccount:agents:researcher
+egress:
+ allow:
+ - api.github.com
+```
+
+Writing that file is not enough to become that agent. `sam-box` verifies a
+platform credential — a Kubernetes projected service account token, for example
+— and accepts the bundle only if the credential's subject matches
+`external_id`. The mesh identity is a claim about a platform identity that
+something else already vouched for.
+
+On every request the gateway asserts the agent to the node, overwriting
+anything the sandbox tried to set. Mesh policy can then be written about the
+agent rather than about the host it happens to run on.
+
+## The architecture
+
+```mermaid
+flowchart LR
+ subgraph sandbox["sandbox: no network, no DNS, no credentials"]
+ H["agent harness<br/>(your code)"]
+ end
+
+ subgraph host["host"]
+ B["sam-box<br/>one per agent<br/>holds no mesh identity"]
+ N["sam-node<br/>one per host<br/>the mesh member"]
+ end
+
+ M(["the mesh<br/>models · tools · peers"])
+
+ H -- "SOCKS5 over a unix socket" --> B
+ B -- "node API socket<br/>+ X-Sam-Agent" --> N
+ N <--> M
+ B -. "allowed names only" .-> E([internet])
+```
+
+Two separations do the work.
+
+**One `sam-node` per host, one `sam-box` per agent.** The node is the mesh
+member: it enrols, holds the mesh identity and maintains peer connections. The
+box holds no identity of its own — it consumes the node's API socket on the
+agent's behalf and names the agent on every request. Adding an agent therefore
+costs a `sam-box`, not a mesh member: [measured at about 18 MB and 59 ms](../../scale-report/),
+rather than a new enrolment and a new peer in the DHT.
+
+**The node's API stays on the node's side of the boundary.** An agent never
+reaches it. What the agent gets is the curated surface the gateway builds on
+top: inference, tools, and permitted egress. The node's own control endpoints —
+service registration, peer management — are not part of it.
+
+## Running the example
+
+The example harness is in
+[`development/examples/agent-harness`](https://github.com/google/sam/tree/main/development/examples/agent-harness).
+It is about a hundred lines and does something real: discovers tools, calls a
+model, runs the tool loop, stops when done.
+
+### 1. A node
+
+You need a `sam-node` enrolled in a mesh, serving its API on a socket:
+
+```bash
+sam-node run --socket-path /run/sam/node.sock --data-dir /var/lib/sam
+```
+
+### 2. A boundary for the agent
+
+```bash
+sam-box run \
+ --socket /run/sam/agent.sock \
+ --sidecar-socket /run/sam/node.sock \
+ --bundle ./bundle.yaml \
+ --credential-issuer https://kubernetes.default.svc \
+ --credential-audience sam
+```
+
+Credential verification is on by default. For a local experiment where there is
+no issuer to verify against, `--insecure-unverified-bundle` turns it off and
+says plainly what you are giving up: whoever can write the bundle decides which
+agent this sandbox is.
+
+### 3. The sandbox
+
+The agent needs the boundary socket and nothing else. For a container:
+
+```bash
+docker run --rm \
+ --network none \
+ --cap-add NET_ADMIN \
+ --device /dev/net/tun \
+ -v /run/sam/agent.sock:/run/agent.sock \
+ agent-harness "Summarise the open issues in our repo"
+```
+
+`--network none` is the assertion, not just the arrangement. If any of this
+worked because the container could route somewhere, it would be proving nothing.
+
+Notice what is *not* passed: no API key, no mesh token, no endpoint, and **no
+proxy variable**. The sandbox builds one `tun0`, makes it the default route and
+points `tun2socks` at the boundary. The agent asks for `mesh.sam.alt` like any
+other host and its traffic leaves through the tun because there is nowhere else
+for it to go.
+
+That distinction is worth dwelling on, because the obvious alternative is to set
+`HTTP_PROXY` and be done. SAM used to do exactly that, and it was the wrong
+layering: an agent that has to *cooperate* with its own confinement is not
+confined. The next library that ignores the convention, the next subprocess that
+clears its environment, the next protocol that is not HTTP — each one is outside
+the boundary. Routing does not have that failure mode, because nothing has to
+agree to it.
+
+### 4. Watch what it did
+
+```bash
+curl -s http://127.0.0.1:9600/metrics | grep sam_box_flows_total
+```
+
+Every flow the agent opened, by route class and outcome, including the ones
+that were refused. Refusals never appear as latency, so counting them is the
+only way to see them.
+
+## In a microVM
+
+A container shares the host kernel. For an agent running code a model wrote, or
+code from somewhere you do not control, that may not be a boundary you want to
+rely on. Firecracker gives each agent its own kernel for a few tens of
+milliseconds of boot time.
+
+The layering is unchanged, and that is the useful part — the microVM swaps out
+how the sandbox reaches the socket, not what the agent does:
+
+```mermaid
+flowchart LR
+ subgraph vm["Firecracker microVM: own kernel, no NIC"]
+ A["agent harness"]
+ T["tun2socks<br/>tun0, default route"]
+ A -- "plain HTTP to mesh.sam.alt" --> T
+ end
+ T -- "vsock CID 2" --> V["host: &lt;uds&gt;_1080"]
+ V --> B["sam-box"]
+```
+
+The guest has no network device at all. `tun2socks` presents a `tun0` that is
+the default route and forwards everything to the SOCKS5 boundary over vsock. The
+harness makes ordinary HTTP requests to `mesh.sam.alt` and needs no
+configuration, because from inside the VM there is nothing else it could be
+doing.
+
+Names are resolved by the boundary rather than in the guest, which is why the
+sandbox needs no resolver: `tun2socks` runs with virtual DNS, so `mesh.sam.alt`
+is handed to the boundary as a name instead of being looked up and failing.
+
+Every address inside the sandbox is link-local (`169.254.0.0/16`), which is
+what those addresses are for: RFC 3927 describes a single link with no router,
+and a tun to the boundary is exactly that. It also means nothing in the sandbox
+can be confused with a real destination — a sandbox numbered out of
+`10.0.0.0/8` will eventually be deployed somewhere that already uses it. The
+resolver address is a fiction that never receives a packet; virtual DNS answers
+inside `tun2socks`.
+
+One detail costs people an afternoon: Firecracker's vsock multiplexes guest
+connections onto **`<uds_path>_<port>`** on the host. A guest connecting to CID
+2 port 1080 arrives on `/var/run/sam-vm-1.vsock_1080`, so that is the exact path
+`sam-box --socket` must serve. The host never speaks AF_VSOCK itself, which is
+why the same `sam-box` works for containers and microVMs with no code in it that
+knows the difference.
+
+## Why this shape
+
+The tempting alternative is to give the agent a token and a proxy and trust it
+to behave. That fails in a specific way: the agent is driven by a model, the
+model is driven by text it did not write, and any instruction that can reach
+the model can attempt to reach the network. Holding a credential is what makes
+that attempt worth making.
+
+Here the agent has nothing to steal and nowhere to go. Its identity is asserted
+by something it cannot influence, its model and tools are granted per-agent, and
+its network is a list of names checked on every flow. What it may do is a
+property of the deployment, not of how well the prompt was written.
+
+## See also
+
+- [Agent architecture](../../agent-architecture/) — the design decisions and why the boundary is SOCKS5
+- [What an agent costs](../../scale-report/) — measured memory, startup and enforcement overhead
+- [Secure gateway](../secure-gateway/) — the gateway's configuration surface