Skip to content

Agent Mesh

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.md
index 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 at
runtime, 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 UX
diff --git a/site/content/docs/user/running-agents.md b/site/content/docs/user/running-agents.md
index 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. With
a 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: -f2
tun0
```
-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 shape
diff --git a/site/content/docs/user/secure-gateway.md b/site/content/docs/user/secure-gateway.md
index 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 bundle
does not list. When the gateway stops, the service is withdrawn, so a suspended
agent 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.
---