Skip to content

Agent Mesh

docs: design the agent sandbox datapath and identity model

Antonio Ojea3cb66ebc3f1c
diff --git a/site/content/docs/agent-architecture.md b/site/content/docs/agent-architecture.md
new file mode 100644
index 00000000..b9b39698
--- /dev/null
+++ b/site/content/docs/agent-architecture.md
@@ -0,0 +1,796 @@
+---
+title: "Agent Architecture"
+weight: 15
+---
+
+# Agent Sandbox Architecture
+
+This document defines how an **agent** — an unmodified harness such as
+`cmd/chaos-agent`, a LangChain script, or Claude Code — is connected to the
+Sovereign Agent Mesh when it runs inside a sandbox (a Firecracker microVM or a
+`--network none` container).
+
+It is a design document: it states the layering, the contracts each layer
+exposes, and the tests that hold those contracts in place. Scale testing depends
+on this being settled, not the other way round.
+
+## 1. Goals
+
+1. **The harness is unmodified and mesh-unaware.** It opens ordinary sockets, it
+ resolves ordinary names, it speaks ordinary HTTP. No SDK, no `LD_PRELOAD`, no
+ proxy environment variables it has to honour.
+2. **One enforcement point.** Every packet the sandbox emits is authorized in
+ exactly one place, by name, against one policy.
+3. **The sandbox has no network.** Not a filtered network — *no* network device
+ other than the one we hand it. Isolation is a property of the runtime
+ (`network=none`, a microVM without a tap device), not of a firewall rule.
+4. **The mesh looks like the internet.** Reaching a remote model or a remote MCP
+ server is the same act as reaching `api.github.com`: connect to a name. Which
+ names are mesh-internal and which are public is a policy decision made on the
+ host, not a code path in the agent.
+5. **Deps stay put.** The design below adds no `go.mod` entry (see §9).
+
+## 2. What is wrong with the current layering
+
+Today there are three independent interception mechanisms and two overlapping
+local dataplanes.
+
+`cmd/nano-init` intercepts at the application layer, three ways at once:
+
+* a **DNS spoofer** on `127.0.0.1:53` plus a rewritten `/etc/resolv.conf`,
+* **`HTTP_PROXY`/`HTTPS_PROXY` injection** into the child's environment,
+* an optional **`LD_PRELOAD` socket interceptor**, shipped per architecture and
+ per libc from the gateway's `/internal/bootstrap/libinterceptor.so`.
+
+Each one leaks. Proxy variables are honoured only by HTTP-aware clients — a
+harness that opens a raw socket, a Python library using `httpx` with
+`trust_env=False`, or anything speaking gRPC or Postgres simply escapes. DNS
+spoofing forces every flow through a MITM even when no secret needs injecting,
+and it answers with loopback addresses, which destroys the destination name the
+policy engine actually wants to reason about. The `LD_PRELOAD` shim has to be
+built and served for every arch/libc pair, and is defeated by a static binary.
+The `nano-init` README is explicit that this is deliberate ("HTTP is an
+opinionated waist"), and that reasoning was sound when the only capability was
+HTTP. It stops being sound the moment an agent needs to `git clone`, or the
+moment a sandbox needs a deny-by-default network.
+
+Meanwhile there are two host-side dataplanes with disjoint capabilities:
+
+| | `sam-node` sidecar | `sam-box` gateway |
+|---|---|---|
+| Local MCP (`/mcp`) | yes | no |
+| OpenAI facade (`/v1/*`) | yes | no |
+| Mesh egress to a peer (`/sam/<peer>/…`) | yes | no |
+| Internet egress | no | yes |
+| Secret injection (MITM CA) | no | yes |
+| Domain filtering | no | no |
+| Own libp2p host + enrollment | yes | yes (duplicated) |
+
+An agent that wants inference *and* `api.github.com` cannot be served by either
+one. `scripts/microvm-init.sh` shows the seam directly: it starts `tun2proxy`
+pointed at the `sam-box` UDS **and** hands the harness
+`--mcp-url http://127.0.0.1:8080/mcp`, two mutually exclusive assumptions about
+what is listening on that port. It is also wired incorrectly — Firecracker
+multiplexes guest→host vsock connections onto `<uds_path>_<port>`, so the guest's
+`VSOCK-CONNECT:2:8080` surfaces on the host as `sam-box-1.sock_8080` while
+`sam-box` listens on `sam-box-1.sock`.
+
+Neither dataplane can filter by domain, which is the one network capability the
+use case actually asks for.
+
+## 3. The layering
+
+One socket, one protocol, one policy point. SOCKS5 is the waist.
+
+```text
+┌─ sandbox (microVM, or container with network=none) ───────────────┐
+│ │
+│ harness (unmodified: sockets + DNS + HTTP) │
+│ │ IP │
+│ tun0 ── default route, the only device besides lo │
+│ │ │
+│ tun2socks ── IP flows → SOCKS5, destination kept as a NAME │
+│ │ (virtual-DNS / fake-IP, see Decision 2) │
+└────────┼──────────────────────────────────────────────────────────┘
+ │ one byte stream
+ │ microVM : AF_VSOCK → firecracker → host UDS <uds>_<port>
+ │ container: bind-mounted UDS
+┌────────┼──────────────────────────────────────────────────────────┐
+│ host ▼ │
+│ sam-box (one per sandbox, NO libp2p host, NO enrollment) │
+│ = SOCKS5 server = THE policy enforcement point │
+│ │ │
+│ ├── node.sam.alt ── byte pipe ───────────┐ │
+│ ├── <svc>.<type>.sam.alt ── HTTP: discover, then ┤ │
+│ │ /sam/<peer>/<type>/… │ │
+│ └── anything else ── deny-by-default domain │ │
+│ policy, opt-in MITM + │ │
+│ secret injection │ │
+│ │ ▼ │
+│ │ sam-node sidecar │
+│ ▼ UDS: /mcp /v1/* │
+│ the internet /sam/* │
+└─────────────────────────────────────────────────────┼─────────────┘
+ │ libp2p
+ mesh
+```
+
+### Decision 1 — SOCKS5, not HTTP CONNECT, is the sandbox boundary protocol
+
+SOCKS5 is chosen for three properties HTTP proxying does not have:
+
+* **It carries the destination name.** `ATYP=0x03` is a domain name. The gateway
+ authorizes `api.github.com`, not `140.82.121.5`. Domain filtering therefore
+ needs no DNS interception, no MITM, and no IP allowlists that rot.
+* **It is protocol-agnostic.** TCP is TCP. `git`, Postgres, gRPC and a raw socket
+ are all first-class; HTTP becomes a payload rather than a requirement.
+* **It has a refusal vocabulary.** Reply `0x02 connection not allowed by
+ ruleset` is a policy denial the guest kernel turns into a clean
+ `ECONNREFUSED` — exactly what an agent should observe when it reaches for
+ something it may not have. UDP (`UDP ASSOCIATE`) is specified but stays **out
+ of scope** for v1: deny it, so the only way out is a named TCP flow.
+
+HTTP MITM does not disappear; it moves *above* the waist. When a domain is
+configured for secret injection, the gateway terminates TLS for that flow with
+the existing `internal/sambox` ephemeral CA and injects the header. Every other
+flow is a byte pipe with no interception at all — a meaningful improvement over
+the status quo, where every flow is MITM'd.
+
+### Decision 2 — names are resolved on the host, never in the guest
+
+`tun2socks` runs with a virtual-DNS pool (fake IPs out of `198.18.0.0/15`). The
+guest resolver gets a synthetic address, `tun2socks` maps that address back to
+the FQDN when the flow opens, and the gateway receives the FQDN in the SOCKS5
+request. Nothing in the guest ever performs a real DNS lookup, so:
+
+* `nano-init`'s DNS spoofer, `/etc/resolv.conf` rewrite, `HTTP_PROXY` injection
+ and `libinterceptor.so` bootstrap are **deleted**, not reimplemented;
+* the guest cannot exfiltrate over DNS, because there is no resolver path out;
+* the policy engine gets the name for free, on every flow, for every protocol.
+
+### Decision 3 — the host never speaks AF_VSOCK
+
+Firecracker's vsock device already terminates AF_VSOCK and hands the host a Unix
+socket per guest port (`<uds_path>_<port>`). The gateway therefore accepts on a
+`net.Listener` that is *always* a UDS. A microVM and a `network=none` container
+become the same code path, and the difference is one line of sandbox setup:
+
+| sandbox | guest side | host side |
+|---|---|---|
+| Firecracker microVM | `tun2socks` → vsock CID 2, port *P* | listener on `<uds>_P` |
+| container, `network=none` | `tun2socks` → `/run/sam/agent.sock` | listener on the bind-mounted path |
+
+This keeps AF_VSOCK out of the Go code entirely (no new dependency) and — more
+importantly for the test pyramid — makes the whole datapath exercisable in a Go
+integration test against a UDS in `t.TempDir()`, with no VM and no KVM.
+
+### Decision 4 — a mesh name is the service namespace written in DNS shape
+
+The mesh already has a canonical namespace: `mcp://<service>`,
+`inference://<service>`, `system://sam.catalog`, and internally
+`libp2p://<peer>/<type>/<service>/…`. That namespace is what the control plane
+authorizes in `allowed_services` and what lands in the Biscuit `service()` fact.
+Sandbox names are a **projection of it**, not a second namespace:
+
+```text
+inference://openrouter <-> openrouter.inference.sam.alt
+mcp://code-reviewer <-> code-reviewer.mcp.sam.alt
+(local sidecar) <-> node.sam.alt
+```
+
+The mapping is declared once, in [`api/names.go`](https://github.com/google/sam/blob/main/api/names.go)
+(`MeshZone`, `LocalNodeHost`, `MeshHost`, `ParseMeshHost`), so the gateway and
+the node cannot drift. The rule that keeps it honest: **never introduce a
+routing decision expressible in one form but not the other.**
+
+`.alt` is the pseudo-TLD reserved by RFC 9476 for namespaces that are
+deliberately *not* resolved through the DNS — which is exactly what these are.
+It cannot collide with a delegated gTLD, and a name that escapes a sandbox fails
+closed instead of resolving to somebody else's host. `.local` was rejected: it
+is mDNS's (RFC 6762) and resolvers treat it specially.
+
+Provider selection is *not* in the name. `openrouter.inference.sam.alt` says
+which service, never which peer; that stays a discovery decision, scored by the
+existing provider scorer. Pinning a peer would mirror `libp2p://<peer>/…` as a
+longer name, but needs a DNS-safe peer encoding first — base58 peer IDs are
+case-sensitive and DNS labels are not. IPFS hit the same wall and solved it with
+lowercase base36 CIDs in subdomain gateways; that is the path if we ever need
+it, and it is noted in `api/names.go` rather than half-built.
+
+### Decision 5 — the agent is the principal; the node is only the channel
+
+Traceability and granular policy are the product. "Agent `foo` may use
+`inference://X`, agent `bar` may not" has to be a statement the *whole mesh* can
+evaluate, and it has to survive an agent being paused on one node and resumed on
+another. So agent identity travels with the agent, never with the host.
+
+A Biscuit is bound to a peer ID: `SamNode.Authorize` requires a `node(<peer>)`
+fact matching the connecting peer and enforces `BaselineReplayCheck`
+(`client_peer_id == connection_peer_id`). That binding is right — for the
+*channel*. It is the wrong place to express *who is asking*.
+
+The mesh already knows how to take in a foreign identity, and agents reuse that
+pattern one level down. A node presents an OIDC JWT **once**, at enrollment; the
+control plane verifies it against a configured issuer and mints a Biscuit;
+`translateClaimsToFacts` turns claims into facts, and the JWT never appears on
+the datapath again. The two domains are joined at exactly one point and never
+mixed:
+
+| | asserted by | verified against | when | on the datapath as |
+|---|---|---|---|---|
+| node identity | control plane | the OIDC issuer | enrollment | a Biscuit |
+| agent identity | the enrolled SAM component that admitted the agent | the platform's workload issuer (K8s SA token, pod certificate, SVID) | admission | an appended Biscuit block |
+
+The agent's facts ride as an **attenuation block appended to the node token**,
+not as a second credential. `biscuit-go` cannot verify a block signed by a third
+party (§10.2), so splitting them buys no extra cryptographic attribution while
+costing a second verification on every request. The identifier is still the
+agent's and still portable: teleport the actor to another worker and the SAM
+component there verifies the same workload credential and asserts the same
+`agent:` name. Nothing downstream notices the move.
+
+The residual trust, stated plainly: an enrolled node asserts its own agents.
+Mesh policy bounds that by binding namespaces to node attestation — only nodes
+attested `cluster=c1.acme` may assert `agent:*.c1.acme` — which the existing
+target-fact machinery already expresses. Non-repudiation *by the agent itself*
+needs proof of possession, which stays an upgrade path (§10.6).
+
+## 4. Where the gateway lives — DECIDED: `sam-box`, without a libp2p host
+
+`sam-node` and `sam-box` currently answer this twice: both run a libp2p host and
+both enroll. The decision is to keep two binaries but give them disjoint jobs.
+
+**`sam-node` — the mesh member.** Unchanged. It owns the libp2p host,
+enrollment, identity, discovery and the sidecar API (`/mcp`, `/v1/*`,
+`/sam/service/*`, `/sam/<peer>/…`) over TCP and its Unix socket.
+
+**`sam-box` — the sandbox dataplane.** One per sandbox. It holds **no libp2p
+host, no enrollment, no mesh identity**. It serves SOCKS5 on the sandbox-facing
+socket, enforces the egress policy, does MITM/secret injection where configured,
+and reaches the mesh solely by dialling the local `sam-node` sidecar Unix socket
+as a client.
+
+What this buys:
+
+* *N* sandboxes per host still share **one** libp2p host, so no *N*× DHT
+ clients, identify/ping loops or router connections — the thing that would
+ otherwise cap density in the scale experiment.
+* `sam-box` becomes small and boring: a SOCKS5 server plus an HTTP client. No
+ `join`, no OIDC, no Biscuit handling, no bbolt store. Most of
+ [cmd/sam-box/main.go](cmd/sam-box/main.go) is deleted.
+* The blast radius of a compromised sandbox stops at its `sam-box`, which holds
+ one agent credential and can be killed and reissued in isolation.
+* Failure isolation and lifecycle match the sandbox's, not the host's.
+
+`sam-box` is a **multiplexer of agents**: it may serve one agent per socket, or
+many agents over one socket, and each flow it forwards carries that agent's own
+identity (Decision 5, §10). Losing the libp2p host costs it nothing here — the
+agent's authority never came from the host in the first place.
+
+`internal/sambox` keeps the ephemeral CA and secret injection and gains the
+SOCKS5 server; `internal/node` keeps everything mesh.
+
+## 5. Contracts
+
+### 5.1 What the harness sees
+
+```bash
+OPENAI_BASE_URL=http://node.sam.alt/v1 # inference, provider chosen by policy
+MCP_URL=http://node.sam.alt/mcp # tools: local catalog + remote services
+SAM_API_TOKEN=<per-sandbox token> # X-Sam-Authentication for the two above
+```
+
+No `HTTP_PROXY`. No CA bundle, unless a domain is explicitly configured for
+secret injection. No mesh concepts. `cmd/chaos-agent` already takes `--mcp-url`
+and `--inference-url`, so it needs no change beyond the values it is given.
+
+A harness that wants one specific service instead of policy-chosen routing uses
+its mesh name directly: `http://code-reviewer.mcp.sam.alt/`.
+
+### 5.2 Gateway dispatch
+
+Applied to the SOCKS5 request's `(host, port)` — `host` is the name
+`tun2socks` preserved, never an IP — in order:
+
+1. **`node.sam.alt`** (`api.IsLocalNodeHost`) → **byte pipe** to the local
+ `sam-node` sidecar Unix socket. `sam-box` parses nothing: `/v1/*`, `/mcp` and
+ `/sam/*` behave exactly as they do over TCP today, including
+ `X-Sam-Authentication` and the `Authorization` passthrough rules. `sam-box`
+ injects the sandbox's token only if the request carries none.
+2. **`<service>.<type>.sam.alt`** (`api.ParseMeshHost`) → `sam-box` terminates
+ HTTP and rewrites onto the sidecar's existing surface:
+ `GET /sam/service/discover?type=<type>&name=<service>` picks a provider, then
+ the request is reverse-proxied to `/sam/<peer>/<type>/<service>/<path>`. No
+ new sidecar endpoint, no libp2p in `sam-box`.
+3. **anything else** → egress policy (§5.3). Allowed flows are dialled directly;
+ flows on a secret-injection domain are terminated with the ephemeral CA.
+4. **no match, or a name in the zone that resolves to nothing** → SOCKS5 reply
+ `0x02`.
+
+Case 2 is the only one that inspects payload, and only because provider
+selection is an HTTP-level decision. `https://` to a mesh name therefore needs
+the ephemeral CA trusted in the guest; v1 documents mesh names as `http://`
+(the transport underneath is libp2p, already authenticated and encrypted) and
+leaves guest CA installation to sandbox image build rather than a bootstrap
+endpoint.
+
+### 5.3 Egress policy
+
+Deny-by-default, evaluated on the name, expressed in the node config next to the
+existing `attenuation` block:
+
+```yaml
+version: v1
+sandbox:
+ egress:
+ allow:
+ - "api.github.com"
+ - "*.pypi.org"
+ secrets:
+ "api.github.com":
+ kind: bearer
+ value_from: /etc/sam/secrets/github
+```
+
+Filtering by name without MITM is honest here: the gateway dials the name it
+authorized and, for TLS, requires the client's SNI to match it.
+
+## 6. Test plan
+
+Coverage is pushed as far down the pyramid as it will go. Firecracker appears
+exactly once, at the top.
+
+**Unit (`internal/…`, `api/`).** SOCKS5 request/reply codec; the name↔URI
+projection (`api/names_test.go`, already landed); dispatch classification
+(`node.sam.alt` / mesh name / public / denied); wildcard matching in the
+allowlist; SNI-vs-authorized-name mismatch. Pure functions, microseconds.
+
+**Integration (`tests/integration/`, budget 10s each).** The whole datapath, no
+containers:
+
+* node A registers a fake OpenAI-compatible backend — reuse the
+ `registerInferenceService` + `httptest` pattern already in
+ `openai_facade_test.go`;
+* node B registers a fake MCP service — reuse `newFakeMCPHandler`;
+* node C runs with a sidecar Unix socket, and a `sam-box` beside it serves
+ SOCKS5 on a second socket in `t.TempDir()`;
+* the test drives a real SOCKS5 client (`golang.org/x/net/proxy`, already a
+ direct dependency) over that socket and asserts:
+ 1. `node.sam.alt:80` → `/v1/chat/completions` reaches A's fake LLM across the mesh,
+ 2. `node.sam.alt:80` → `/mcp` `call_remote_tool` reaches B's fake MCP,
+ 3. `<svc>.mcp.sam.alt:80` resolves through discovery to B and reaches it,
+ 4. an allowlisted public name reaches a local `httptest` server,
+ 5. a non-allowlisted name is refused with SOCKS5 `0x02`,
+ 6. the sandbox's sidecar token never appears in what A, B or the public
+ server receive.
+
+**E2E (`tests/e2e/*.bats`).** Two CUJs, no more:
+
+* *Container sandbox*: `docker run --network none` with the real harness plus
+ `tun2socks`, a bind-mounted UDS to a host `sam-node`, against the existing bats
+ mesh (`lib/container_mesh.bash`). Asserts a real inference call, a real tool
+ call, and one blocked domain.
+* *microVM sandbox*: the same rootfs under Firecracker, `skip` unless `/dev/kvm`
+ is present. It exists to prove the vsock↔UDS mapping and nothing else; every
+ behavioural assertion is already covered above.
+
+The draft `tests/e2e/agent_scenarios.bats` is superseded: its scenario 1 asserts
+`/v1/models` over the sidecar UDS (an integration-level fact) and its scenario 2
+depends on live `api.github.com` reachability (a flake).
+
+## 7. What gets deleted
+
+* `cmd/nano-init`'s DNS spoofer, `/etc/resolv.conf` rewrite, `HTTP_PROXY`
+ injection and interceptor bootstrap. What remains worth keeping is PID 1
+ hygiene — zombie reaping, signal propagation, exit-code passthrough — plus, if
+ we own the guest side in Go, `tun0` setup.
+* `internal/sambox`'s `/internal/bootstrap/libinterceptor.so` endpoint and the
+ `--interceptors-dir` flag.
+* `sam-box`'s entire mesh half: `join`, OIDC/device-code enrollment, the bbolt
+ store, `node.SamNode` construction, relay/bootstrap/router flags. It keeps
+ `run`, the sandbox socket, the egress policy and the ephemeral CA, and gains
+ `--sidecar-socket` + a token.
+* The contradictory URL/proxy wiring in `scripts/microvm-init.sh`.
+
+## 8. Migration order
+
+1. Land the SOCKS5 server and dispatch in `internal/sambox`, with unit +
+ integration coverage, behind the existing `sam-box run -u`. Nothing else
+ changes yet.
+2. Strip `sam-box`'s mesh half; it becomes a client of the `sam-node` sidecar
+ socket.
+3. Point `scripts/microvm-init.sh` and the container path at it; fix the
+ `<uds>_<port>` mapping. Add the two bats CUJs.
+4. Strip `nano-init` to PID 1 duties + `tun0`.
+5. *Then* resume scale testing, on a datapath whose failure modes are known.
+
+## 9. Dependencies
+
+Nothing on the host requires a `go.mod` change:
+
+* SOCKS5 **server** — a few hundred lines against the stdlib; we implement only
+ `CONNECT` with `NO AUTH` (RFC 1928) on a Unix socket.
+* SOCKS5 **client** (tests) — `golang.org/x/net/proxy`, already a direct dep.
+* AF_VSOCK — never touched by Go code (Decision 3).
+* MITM CA and secret injection — `internal/sambox`, already ours.
+* Mesh name projection — `api/names.go`, stdlib only.
+
+### 9.1 The guest-side tun2socks — decided, with an exit
+
+**Decision: keep the external binary.** `scripts/build-rootfs.sh` downloads a
+release of the Rust `tun2proxy` into the guest rootfs. It is a guest-image
+artifact, not a Go dependency, so `go.mod` stays clean and the host binaries stay
+unaffected.
+
+What we accept by doing so:
+
+* a third-party release URL is pinned into the image build. It **must** be pinned
+ by SHA-256 and verified after download — today the script does neither, which
+ is a supply-chain hole in an artifact that sees every byte the agent sends;
+* a second language toolchain in the sandbox image;
+* the guest datapath is not covered by `make test`, only by the bats CUJ.
+
+What would trigger the switch to an in-guest Go implementation:
+
+* needing to make policy or telemetry decisions *inside* the guest (per-process
+ attribution, for instance) — `tun2proxy` cannot be extended from here;
+* needing architectures the project does not publish binaries for;
+* the release URL becoming unavailable or unverifiable.
+
+That switch means a userspace TCP/IP stack — `gvisor.dev/gvisor/pkg/tcpip` is
+the realistic option — which is a **new dependency requiring explicit
+approval**, and a large one. It is not blocked by anything in this design: the
+sandbox boundary is SOCKS5 over a byte stream either way, so replacing the guest
+implementation changes nothing on the host and no test above needs rewriting.
+The guest-side code carries this note inline so the trade-off is visible where
+the decision would be made.
+
+## 10. Agent identity
+
+### 10.1 Requirements
+
+1. **Portable.** An agent paused on node A and resumed on node B is the same
+ principal. Identity moves with the agent's state, never with the host.
+2. **Verifiable mesh-wide.** Any peer can decide "agent `foo` may use
+ `inference://X`, agent `bar` may not" without asking anyone.
+3. **Scales to 10⁹ agents and services.** No central per-agent record, no
+ per-agent mint on the hot path, no enumeration in any policy document, no
+ revocation list proportional to the agent population.
+
+### 10.2 The library constraint that decides the shape
+
+`biscuit-go/v2 v2.2.0` has **no third-party blocks**: the library's own sample
+suite explicitly skips `test024_third_party.bc`, and the API exposes no
+public-key (`trusting`) checks. So an agent-signed block cannot be embedded
+inside the node's token.
+
+What the library *does* give us is exactly enough:
+
+* `New` — mint under a root key;
+* `CreateBlock` + `Append` — **offline attenuation**, no root key, no network;
+* multi-root verification (`VerifyBiscuit(..., trustedPublicKeys, ...)`);
+* `RevocationIds()` — per-block revocation identifiers;
+* `Seal` — stop further attenuation.
+
+Hence the agent's facts travel as an ordinary appended block on the node token
+(Decision 5). This is not a workaround — it is why **`Authorize` needs no change
+at all**: appended blocks are already part of the token and already evaluated,
+so only the component that admits the agent has to learn to append. If
+`biscuit-go` later gains third-party blocks, the agent can sign its own block
+and non-repudiation arrives without a wire break.
+
+### 10.3 Why it scales: delegation, not enumeration
+
+Three rules, each of which removes a per-agent bottleneck:
+
+**Minting is offline and local.** The control plane never mints per agent. It
+grants a *namespace holder* — in practice the enrolled `sam-node`/`sam-box` in a
+cluster, scoped by its attestation (§10.6) — authority over an agent namespace,
+once. That holder asserts a per-agent identity by appending a block to its own
+token with `Append`: no root key, no round trip, no central state. Admitting an
+agent is O(1) local work, which is the only way 10⁹ of them exist.
+
+**Policy is written over namespaces, not identities.** This needs almost no new
+machinery, because the existing vocabulary is already shaped for it:
+`BuildTargetDatalogFacts` compiles targets into `granted_target_prefix`,
+`granted_target_suffix`, `granted_target_set` and `granted_target_exact`. Making
+`agent` a first-class principal is:
+
+* `FactAgent = "agent"` in `api/datalog.go`;
+* `FactAgent` added to `ValidMemberPrefixes` in `api/policy.go`;
+* the agent block's `agent(...)` fact injected as a `target_fact` at
+ authorization time.
+
+After that, `allowed_targets: ["agent:acme/prod/*"]` works with **zero new
+evaluation logic**, and "foo yes, bar no" is expressed as a namespace, a set or
+a prefix — never as a list of a billion names.
+
+**Revocation is tiered.** A revocation list sized like the agent population is
+not a design, so nothing depends on one:
+
+| what happened | mechanism | cost |
+|---|---|---|
+| agent is done or misbehaving | kill the sandbox | instant, local, free |
+| credential must stop being usable elsewhere | short-lived workload credential; the platform stops renewing it | bounded window, no list |
+| a namespace holder is compromised | `RevocationIds()` on its delegation block | one entry kills every agent under it |
+
+### 10.4 How the identity travels
+
+The agent's credential bundle lives **in the agent's own state**, next to
+whatever else the platform migrates — not in `sam-box`'s configuration and not in
+the node's store. Pause, snapshot, move, resume: `sam-box` on node B reads the
+bundle from the migrated state and starts asserting it. **No control-plane call
+on resume.** That is what makes migration cheap, and it is the same property
+that makes 10⁹ agents possible.
+
+### 10.5 Where the agent's identity comes from
+
+Not from the agent. The harness stays unmodified (Goal 1), so it never asserts
+anything about itself — it could only lie. It comes from the credential the
+platform **already** issues to the workload:
+
+* a **Kubernetes projected service-account token**, audience-scoped and
+ short-lived;
+* a **pod certificate** (KEP-4317) — which Substrate already provides today via
+ its `podcertcontroller` polyfill;
+* a **SPIFFE SVID**, where SPIRE is in play.
+
+`sam-box` verifies that credential against the platform's issuer at admission —
+in-cluster, cheap, no mesh round trip — and translates it into `agent:` facts by
+the rules in §10.8. **The scheduler needs no mesh enrollment and no mesh
+credential of its own.** It keeps doing exactly what it already does for every
+workload: project an identity document. This is the OIDC relationship, not a
+merger of the two domains.
+
+`sam-box` then binds that identity to the channel, so nothing has to be asserted
+in-band afterwards:
+
+1. **One socket per agent (default).** Identity is a property of the socket,
+ fixed when the sandbox is created: one vsock UDS per microVM, one bind-mounted
+ socket per container. Nothing in-band, nothing to spoof.
+2. **SOCKS5 username (multiplexing).** When one `sam-box` fronts many agents over
+ one socket, the RFC 1929 username/password sub-negotiation carries the agent
+ id and its admission token. It is standard, in-band, supported by every SOCKS
+ client and by `tun2proxy` (`socks5://user:pass@host`), and it makes identity
+ **per-connection** — which is exactly what a multiplexer needs.
+
+### 10.6 The honest limit
+
+An enrolled node asserts its own agents, so a compromised node can assert any
+agent identity **within the namespaces its own attestation permits**. That bound
+is the mitigation, and it is enforced by the same policy machinery as everything
+else; without the namespace binding, a single compromised node could impersonate
+any agent anywhere, which is why it is not optional.
+
+Removing the residue entirely requires proof of possession: the agent holds a
+key and signs a per-request binding. That needs either a mesh-aware harness
+(violates Goal 1) or a signer inside the sandbox, and it needs third-party
+blocks in `biscuit-go` to be attributable. It is a clean upgrade, not a rewrite.
+
+### 10.7 Consequences for the plan
+
+* `api/` — `FactAgent`, `ValidMemberPrefixes`, the §10.8 translation helpers, and
+ the §12 bundle schema.
+* `internal/node` — **nothing** for authorization: appended blocks are already
+ verified and evaluated. Only the namespace-binding policy is new.
+* `internal/sambox` — holds the bundle, attaches it per flow, per socket or per
+ SOCKS5 connection; serves the §12 control socket and the §11 ingress endpoint.
+* `cmd/nano-init` — owns the guest side of the ingress channel (§11.2).
+* Sidecar — propagates the agent header on egress alongside `X-Sam-Biscuit`.
+* Tests — the CUJ that demonstrates the selling point belongs at integration
+ level: two agents behind one `sam-box`, same node, same mesh; `foo` reaches
+ `inference://X` and `bar` is refused, purely on their own credentials.
+
+### 10.8 The agent identifier
+
+**Decided: dot-separated, DNS-shaped, most-specific-first.**
+`agent:reviewer-7.prod.acme.example`, matched by `agent:*.prod.acme.example`.
+
+The policy engine chooses this for us. `BuildTargetDatalogFact` compiles
+`*.acme.example` into a suffix fact that **keeps the leading dot**
+(`.acme.example`) and `acme.*` into a prefix fact that **keeps the trailing dot**
+(`acme.`). Wildcards are therefore already anchored on dot boundaries:
+`evil-acme.example` cannot match `*.acme.example`. A slash-separated
+`agent:acme/prod/name` would need new fact types and new matching code, and
+would reintroduce the boundary bug the dot anchoring already avoids. It also
+matches every other name in the system: service names are validated by
+`dnsNameRegex`, and mesh hosts are DNS-shaped (§Decision 4).
+
+**Is it a mesh-only convention? Yes — and that is fine, for exactly the reason
+you gave.** It is the same relationship the mesh already has with OIDC:
+`translateClaimsToFacts` turns `sub`, `email` and `groups` into `user`, `email`
+and `group` facts, and policy is written against *those*, never against the raw
+JWT. Third parties do not adopt `agent:`; connectors translate into it.
+
+A connector's translation must satisfy four properties, and this is the part
+worth writing down because "without losing capabilities" lives here:
+
+1. **Total** — every foreign identity maps to exactly one mesh identifier.
+2. **Injective** — two foreign identities never collide, or policy leaks across
+ tenants. The rightmost labels must be an authority the platform actually
+ controls.
+3. **Hierarchy-preserving** — foreign hierarchy boundaries must land on dot
+ boundaries. This is the capability-preserving requirement: if the connector
+ flattens the hierarchy, wildcard policies stop being expressible and the
+ operator is forced back to enumeration.
+4. **Auditable** — the original identifier travels verbatim alongside the
+ translated one. Where translation cannot round-trip, the verbatim value is
+ what an auditor reads.
+
+| foreign identity | mesh identifier |
+|---|---|
+| `spiffe://acme.example/prod/reviewer-7` | `agent:reviewer-7.prod.acme.example` |
+| K8s SA `prod/reviewer` in cluster `c1.acme.example` | `agent:reviewer.prod.c1.acme.example` |
+| OIDC `iss=https://acme.example`, `sub=reviewer-7` | `agent:reviewer-7.acme.example` |
+
+Each segment must be a valid DNS label; a connector encodes anything else.
+Non-hierarchical attributes do **not** belong in the name — that is what the
+attested label machinery (`api/labels.go`) is for.
+
+## 11. Ingress: agents that serve
+
+An agent must be able to say "route traffic for this name to me". Two things
+make this smaller than it looks.
+
+**It is not a new namespace.** `code-reviewer.mcp.sam.alt` is already the name
+(Decision 4); serving it just means being its provider. And **the registration
+API already exists**: `RegisterServiceRequest{service{type,name,description},
+target_url}` on `/sam/service/register`.
+
+### 11.1 Declaring
+
+Either the platform declares it at admission (§12), or the agent registers at
+runtime by POSTing to `http://node.sam.alt/sam/service/register` — which already
+works over the egress path, with no new API.
+
+`sam-box` **rewrites `target_url`** to its own per-agent ingress endpoint before
+forwarding the registration. A sandboxed agent must never be able to point the
+mesh at a URL of its choosing: that would turn its node into an open relay and
+hand every agent an SSRF primitive against the host's network.
+
+### 11.2 The reverse channel
+
+Inbound is the one place the datapath is not egress-shaped:
+
+```text
+remote peer → libp2p → sam-node → sam-box ingress endpoint
+ │
+ ▼ one stream per inbound request
+ sandbox boundary
+ │
+ nano-init accept loop
+ │
+ 127.0.0.1:<port> (the agent's listener)
+```
+
+So a sandbox has exactly two channels, one per direction:
+
+| channel | direction | protocol | who listens |
+|---|---|---|---|
+| egress | guest → host | SOCKS5 | host (`sam-box`) |
+| ingress | host → guest | one stream per request | guest (`nano-init`) |
+
+Firecracker's vsock is bidirectional, so host→guest needs no new transport: the
+host connects to the firecracker UDS and writes `CONNECT <port>`, with the guest
+listening on that vsock port. A container gets the symmetric arrangement with a
+second bind-mounted socket. This is also what finally justifies `nano-init`
+beyond PID 1 hygiene: it owns the guest side of the ingress channel.
+
+### 11.3 Authorization closes the loop
+
+Nothing new is needed. `sam-node` authorizes the **caller** — their node token
+carrying their agent block (Decision 5) — before the stream ever reaches
+`sam-box`. "Agent `foo` may call agent `bar`" is therefore one policy statement,
+evaluated at `bar`'s node, with the existing machinery, and both ends are named
+by portable identities rather than by hosts.
+
+### 11.4 Migration
+
+The ingress declaration is part of what travels (§10.4). On resume, `sam-box` on
+node B registers the same name and discovery re-points to node B. The name is
+stable because it belongs to the agent, not to the node — which is the whole
+point of §10.
+
+## 12. The platform integration interface
+
+This is the seam a scheduler or harness connector builds against. It must be
+small, versioned, and the only place identity enters the system.
+
+### 12.1 The agent bundle
+
+What the platform provides per agent. It lives in the agent's state directory, so
+it migrates with the agent by construction:
+
+```yaml
+version: v1
+agent:
+ id: reviewer-7.prod.acme.example # canonical mesh identifier (§10.8)
+ external_id: spiffe://acme.example/prod/reviewer-7 # verbatim, for audit
+ credential: /var/run/secrets/substrate/token # the platform's own workload
+ # credential, verified at
+ # admission (§10.5)
+egress:
+ allow: ["api.github.com", "*.pypi.org"]
+ secrets:
+ "api.github.com": {kind: bearer, value_from: /etc/sam/secrets/github}
+ingress:
+ - {name: code-reviewer, type: mcp, port: 8080}
+```
+
+### 12.2 Operations
+
+Exposed by `sam-box` on a control socket that is **not** reachable from inside
+the sandbox:
+
+| operation | meaning |
+|---|---|
+| `Attach(bundle)` | admit an agent; returns the egress and ingress endpoints to wire into the sandbox |
+| `Detach(agent_id)` | stop it: unregister ingress, close channels, drop credentials |
+| `Refresh(agent_id, credential)` | hand in a rotated workload credential (§10.3) |
+| `Status(agent_id)` | what is registered and connected, for the scheduler's reconcile loop |
+
+### 12.3 Guarantees the interface owes a connector
+
+1. **`Attach` is idempotent, keyed by agent id.** Resume after a crash or a
+ migration is just another `Attach` — no special-case path.
+2. **Identity never arrives in-band from the sandbox.** The platform is the sole
+ identity source (§10.5).
+3. **The agent id is stable across `Attach` on different hosts.** This is what
+ makes migration invisible to the rest of the mesh.
+4. **`Detach` is complete.** No residual advertisement; discovery converges.
+5. **Versioned.** `version: v1`, and the schema lives in `api/`, so it is a real
+ contract and not a convention.
+
+### 12.4 The first connector: Agent Substrate
+
+[Agent Substrate](https://github.com/agent-substrate/substrate) is the
+integration target, and it lines up unusually well:
+
+| Substrate | SAM |
+|---|---|
+| **Actor** (the agent) | the principal: `agent:<actor>.<atespace>.<cluster domain>` |
+| **Atespace** (namespace) | the hierarchy label policy wildcards on |
+| routing by Host `my-counter-1.demo.actors.resources.substrate.ate.dev` | already dot-separated and most-specific-first — the same shape as §10.8 |
+| `podcertcontroller` (KEP-4317 pod certificates), projected SA tokens | the workload credential `sam-box` verifies at admission (§10.5) |
+| `atelet` per-node DaemonSet; `ateom-gvisor` / `ateom-microvm` | where `sam-box` attaches: one sandbox, two channels |
+| suspend/resume with full-state snapshot (RAM + filesystem) | carries the agent bundle with no extra work (§10.4) |
+| `atenet` (DNS, Envoy routing, proxy sidecars, CONNECT) | the seam to negotiate: who owns egress |
+
+The name mapping is a pure string translation with no capability loss, which is
+the §10.8 test: the Host `my-counter-1.demo.actors.resources.substrate.ate.dev`
+becomes `agent:my-counter-1.demo.actors.resources.substrate.ate.dev`, and
+`agent:*.demo.actors.resources.substrate.ate.dev` means "every actor in atespace
+`demo`" — injective, hierarchy-preserving, reversible.
+
+Two things to settle **with** the Substrate side rather than assume:
+
+* **Egress ownership.** `atenet` already supplies DNS, routing, proxy sidecars
+ and CONNECT. The SOCKS5 boundary has to slot in as the sandbox's egress rather
+ than compete with it. `sam-box` behind atenet's sidecar seam is the likely
+ fit, but that is a conversation, not a decision to take unilaterally.
+* **Ingress.** Substrate already routes inbound to actors by Host header. §11
+ must reuse that path rather than build a parallel one: a SAM ingress
+ declaration should end up as a Substrate route.
+
+### 12.5 Still to settle
+
+* **Wire format** for `Attach`/`Detach`/`Refresh`/`Status`: proto in
+ `api/sam.proto` (AGENTS.md's rule) versus a YAML bundle plus a small local
+ HTTP endpoint. Substrate is Go, so proto costs its connector nothing;
+ Python/TypeScript connectors would prefer HTTP. Leaning proto for the
+ operations, YAML for the bundle.
+* **Bulk pre-creation is deliberately not in v1** — premature until the semantics
+ are proven. What v1 owes it is *room*: `Attach` takes a bundle and is
+ idempotent per agent id, so `AttachBatch` is a purely additive operation
+ later, and the offline attenuation in §10.3 already makes it possible with no
+ protocol change.
+
+## 13. Remaining smaller open items
+
+1. **UDP.** Denied in v1. If an agent ever needs QUIC or real DNS, it returns as
+ `UDP ASSOCIATE` under the same name-based policy.
+2. **Guest trust of the ephemeral CA.** Baked into the sandbox image at build
+ time, or re-introduce a bootstrap endpoint? v1 avoids the question by keeping
+ mesh names on `http://` (§5.2).
+3. **Peer-pinned mesh names.** Deferred until a DNS-safe peer encoding is chosen
+ (Decision 4).