Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: the canonical way to run an agent
Antonio Ojeaeb7becfe4fb7
diff --git a/development/examples/agent-harness/Dockerfile b/development/examples/agent-harness/Dockerfilenew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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.yamlnew file mode 100644index 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.shnew file mode 100755index 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.txtnew file mode 100644index 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.2diff --git a/scripts/microvm-init.sh b/scripts/microvm-init.shindex 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 /procmount -t sysfs sysfs /sysmount -t devtmpfs devtmpfs /dev-# Setup localhostip 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 tunip 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/consolereboot -fdiff --git a/site/content/docs/user/running-agents.md b/site/content/docs/user/running-agents.mdnew file mode 100644index 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: <uds>_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