Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: ingress reaches an isolated sandbox, and the harness must be inside one
Antonio Ojeab09f8a9ffa8b
diff --git a/site/content/docs/agent-architecture.md b/site/content/docs/agent-architecture.mdindex 4d716c20..77aac138 100644--- a/site/content/docs/agent-architecture.md+++ b/site/content/docs/agent-architecture.md@@ -757,13 +757,25 @@ the node on the agent's behalf. Two things make that safe:The bundle declares `{name, type}` only. The port is the agent's to choose atruntime, because that is what it actually knows.-**Implemented**, with one gap: reaching back into the sandbox currently means-dialling an address, which works when the gateway shares a network namespace-with the agent — the Kubernetes sidecar case, and what `TestAgentIngressCUJ`-covers end to end. A microVM or a `network=none` container cannot be reached-that way and needs the reverse channel below, which is not built. The seam is-`IngressManager.AgentAddr`, so that channel slots in without changing the-registration path.+**Implemented, including delivery into an isolated sandbox.** Reaching back in+cannot be done by dialling the agent: every sandbox has a network namespace of+its own, so the gateway's `127.0.0.1` is its own loopback and not the agent's.+That is true of all three profiles, because it follows from the isolation+rather than from any one runtime.++The way in is the way out. Egress crosses the boundary over a pathname Unix+socket, which network namespaces do not apply to because it is a filesystem+object. Ingress uses a second one: `nano-init --ingress-socket` serves it from+inside the sandbox, where it can reach the agent at the address the gateway+meant, and `sam-box --agent-ingress-socket` dials it. The handshake is+Firecracker's — `CONNECT <port>`, then `OK` — so a microVM can offer the same+protocol over vsock without the gateway learning the difference.++`TestSandboxServesThroughTheReverseChannel` drives a real sandbox and asserts+both halves: that dialling the agent directly from outside fails, and that the+same agent answers through the channel. The older ingress tests supply their+own `AgentAddr` and so cover the declaration, the policy check and the+forwarding logic, but not the hop that depends on where the agent is.### 9.1.1 Why this is also the better UXdiff --git a/site/content/docs/user/running-agents.md b/site/content/docs/user/running-agents.mdindex 3f15697e..48bf7335 100644--- a/site/content/docs/user/running-agents.md+++ b/site/content/docs/user/running-agents.md@@ -379,7 +379,26 @@ files behind it, so a private `resolv.conf` is a bind mount over a real file,which has to be created somewhere. The `scratch` volume is that somewhere. Witha read-only root filesystem and no writable path, `nano-init` says so and stops.-What the agent sees once this is running is what it would see in a microVM:+### The harness must be nano-init's child++This is the part to get right, and it is easy to get wrong precisely because the+wrong version appears to work.++`nano-init` creates the namespaces and then **starts the agent as its own child+process**, which is how the agent inherits them. So the container's `command`+has to be `nano-init`, with the harness as its arguments:++```yaml+command: ["/usr/local/bin/nano-init", "run", "--create-namespaces",+ "/var/run/sam/agent.sock", "python3", "/app/agent.py"]+```++A container that starts the harness directly — or that starts `nano-init`+alongside it rather than in front of it — leaves the harness in the pod's+network namespace, with `eth0` and the cluster's routes. It will run, it will+reach the boundary if you point it there, and it will not be sandboxed at all.++Check it rather than assume it:```console$ kubectl exec -c agent agent -- ip -o link show | cut -d: -f2@@ -387,7 +406,39 @@ $ kubectl exec -c agent agent -- ip -o link show | cut -d: -f2tun0```-No `eth0`, on a pod that has one.+### If the agent serves the mesh++An agent can publish an MCP service of its own, and delivering a request to it+means reaching *into* the sandbox — which is the direction all of this exists to+prevent. The gateway cannot dial the agent, because the agent's `127.0.0.1` is+inside a namespace the gateway is not in.++The answer is a second Unix socket, for the same reason the first one works: a+pathname socket is a filesystem object, so network namespaces do not apply to+it. `nano-init` serves it from inside the sandbox and connects each arriving+request to the agent's port.++```yaml+# in the agent container+command: ["/usr/local/bin/nano-init", "run", "--create-namespaces",+ "--ingress-socket", "/var/run/sam/agent-ingress.sock",+ "/var/run/sam/agent.sock", "python3", "/app/agent.py"]++# in the sam-box container+args:+ - run+ - --socket=/var/run/sam/agent.sock+ - --sidecar-socket=/var/run/sam/node.sock+ - --agent-ingress-socket=/var/run/sam/agent-ingress.sock+ - --bundle=/etc/sam/bundle.yaml+```++Without `--agent-ingress-socket`, `sam-box` falls back to dialling the agent+directly and warns that this only reaches an agent sharing its network+namespace — which is to say, one that is not sandboxed.++What the agent may serve is still the bundle's decision, not the agent's. The+agent chooses the port, because that is the part only it knows.## Why this shapediff --git a/site/content/docs/user/secure-gateway.md b/site/content/docs/user/secure-gateway.mdindex ba723094..52a3ced5 100644--- a/site/content/docs/user/secure-gateway.md+++ b/site/content/docs/user/secure-gateway.md@@ -138,10 +138,13 @@ cannot name the URL the mesh routes to, and it cannot claim a name its bundledoes not list. When the gateway stops, the service is withdrawn, so a suspendedagent stops being advertised without anyone reconciling anything.-Reaching back into the sandbox currently means dialling the port the agent-announced, which works when the gateway shares a network namespace with it —-the Kubernetes sidecar arrangement. An isolated sandbox needs the reverse-channel described in the architecture document, which is not built yet.+Reaching back into the sandbox cannot mean dialling the agent: a sandbox has a+network namespace of its own, so the gateway's `127.0.0.1` is its own loopback+and not the agent's. Delivery therefore goes over a second Unix socket, served+from inside the sandbox by `nano-init --ingress-socket` and dialled by+`sam-box --agent-ingress-socket`. Without that flag the gateway falls back to+dialling the agent directly and warns, because that only reaches an agent+sharing its network namespace — one that is not sandboxed.---