sand-boxer/docs/bwrap-messages-route.md

Owner-metered Messages route

An explicitly supplied SandboxManager(messages_route=OwnerMessagesRoute(...)) accepts one exact profile/actor/project/run binding and one sandbox. This trusted in-process capability is never loaded from a profile, caller input or stored status. Rein's MessagesOwner constructs it after parent spend admission, using llm-connect's private Unix listener. Only that socket is mounted at /run/sandboxer/messages.sock. The existing bounded byte bridge exposes a namespace-local HTTP base URL. The broker injects an opaque run token, with exact-output redaction, into each child. The actual provider key stays in the trusted forwarding process outside bwrap.

Metered mode requires ext.bwrap, default-deny with an empty egress list, no owner CONNECT allowlist, no setup secrets or provider credential routes, and only standard system read-only mounts. Private owner state cannot overlap source/workspace/runtime or those mounts. No provider key/ledger directory or host network interface is exposed. Workload changes to URLs, proxy variables, Git helpers or HTTP paths cannot create another route. Raw access to the mounted socket still reaches the same metered protocol. Host owner code remains trusted; this adds no public API authority.

Route expiry, ledger admission and revocation belong to rein. Sand-boxer owns namespace confinement and teardown. Tokens are absent from argv and persisted SandboxStatus/inputs. A manager without the ephemeral binding cannot inject the required token into an existing metered broker after a restart. Unknown request liability is retained; bootstrap/recovery must not rebind or mint replacement tokens.

The local proof in rein tests/test_messages_owner.py uses the actual manager, owner execution transport, bwrap namespaces and host-side fake provider. It proves private state and PID separation, only lo, blocked direct host/public-IP access, successful guarded streaming, and no second upstream call after revocation. The combined worker proof also covers allowed commit import and lost-close replay. make check: lint clean, 199 passed. No runtime/profile installation or real secret read occurred. Existing direct-CONNECT profiles/credential delivery remain separate; the factory needs a newly reviewed empty-egress profile and admitted owner bootstrap on Railiance, under SAND-WP-0015-T04 and HFACT-WP-0001-T03/T04.