RFC 0005: Sandbox proxy egress adapter model

[johntmyers]

Summary

Drafts RFC 0005 for reshaping sandbox proxy egress around transport adapters, shared EgressIntent / EgressDecision authorization, and relay-owned byte handling. The proposal covers CONNECT, forward HTTP, DNS, local services, native TCP, supervisor middleware, credential injection, WebSocket/body injection, JSON-RPC, MCP, and optional process identity for sidecar-style modes.

Related Issue

N/A - RFC proposal.

Changes

• Adds RFC 0005 for the sandbox proxy egress adapter model.
• Splits current-state notes, technical details, and implementation plan into RFC appendix documents.
• Documents flow diagrams for unified adapters, relay handling, DNS/native TCP, local services, and deployment modes.
• Accounts for recent networking changes including nftables, supervisor middleware, JSON-RPC/MCP L7 support, and identity-less runtime modes.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

RFC-only documentation change. Ran git diff --check and ASCII scans on the RFC files. Pre-commit was intentionally not run for this RFC draft.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[maruiz93]

Thanks for this RFC — the adapter/authorization/relay separation is a clean model.

I wanted to flag #1633 (supervisor-proxied host-local endpoints) as a consumer of this design. The host.local / host_local: true pattern proposed there is structurally identical to inference.local — the supervisor proxies a CONNECT request to 127.0.0.1:<port> on the host instead of resolving DNS and connecting externally. It works across all deployment modes in the RFC's table because the supervisor always runs in the host/pod network namespace.

The RFC's local service adapter category is the natural home for this, but Phase 8 currently models only the three existing services (inference.local, policy.local, metadata loopback) without a generalization step for policy-declared host-local endpoints.

A few questions:

1. Could Phase 8 include a step for policy-declared host-local endpoints, even if implementation is deferred? Designing the adapter boundary to accommodate this now would avoid bolting it on later.

2. In the context of the EgressTransport enum, would a reserved hostname like host.local become a new local adapter (Option A from feat(proxy): supervisor-proxied host-local endpoints — generalize the inference.local pattern for arbitrary host services #1633), or would a host_local: true flag on a standard endpoint trigger routing through the existing LocalHttp transport (Option B)?

3. The shared destination validation in Phase 2 centralizes SSRF checks — host-local endpoints bypass DNS entirely (the supervisor connects to 127.0.0.1 directly). Does the destination validator need an explicit carve-out for host-local routing, similar to how inference.local bypasses OPA network policy today?

Our use case: we're designing host-side API servers for fullsend (container builder, repo provisioner) and have an ADR and early experiments around it. Today the experiments bind to 0.0.0.0 with allowed_ips — the workaround described in #1633. Supervisor-proxied host-local endpoints would eliminate the network exposure and make the setup driver-agnostic, and we'd like to build on a stable foundation rather than the workaround.

[johntmyers]

@maruiz93 have you tried using host.openshell.internal? so something like:

network_policies:
  host_service:
    name: host_service
    endpoints:
      - host: host.openshell.internal
        port: 8080
    binaries:
      - path: /usr/bin/curl

The service you are running will need to be addressable by the driver infra you choose. For example with Docker the service you are running will need to be reachable by other containers in order for the sandbox workload to reach it through host.openshell.internal.

[maruiz93]

Yes — we tested exactly this pattern in fullsend-ai/experiments#28 (merged, 6 harness configs across 3 discovery methods × 2 network policies). It works, but requires three manual workarounds that motivate #1633:

1. allowed_ips with runtime IP templating. SSRF protection blocks private IPs by default, so the policy needs an explicit allowed_ips entry for the host bridge IP. That IP isn't known until runtime — the orchestrator resolves it with getent hosts host.openshell.internal and templates it into the policy via sed. Without this, the proxy blocks the connection. Your snippet above would hit that.

allowed_ips:
  - "{{HOST_IP}}/32"   # rendered at runtime by the orchestrator

2. Servers must bind to 0.0.0.0. On rootless Podman + pasta, the bridge gateway IP (e.g., 10.88.0.1) lives inside the container namespace — bind() from the host fails with EADDRNOTAVAIL. So host services can't bind to a specific internal interface; it's 0.0.0.0 or nothing, which exposes them on all network interfaces. Bearer token auth mitigates but doesn't eliminate the attack surface.

3. The bridge IP varies by driver. Rootless Podman + pasta uses a link-local address (169.254.1.2), Docker uses a bridge gateway (172.17.0.1), Kubernetes needs explicit host_gateway_ip config, and on macOS/WSL2 the bridge IP is often unreachable from the host entirely (#1358, #811).

These are the problems #1633 targets. The supervisor already solves the structurally identical problem for inference.local — it runs in the host/pod netns, intercepts the CONNECT request, and connects to 127.0.0.1 on the host side. Generalizing that mechanism to policy-declared endpoints would let host services bind to loopback (never network-exposed), eliminate the allowed_ips templating step, and work identically across all drivers.

The experiment findings document all of this in detail: findings — "API servers must bind to all interfaces".

[russellb]

Agent-assisted design review (principal-engineer pass, grounded in the current openshell-supervisor-network code). The direction is sound and the current-state findings check out — comments below focus only on actionable gaps. Inline notes cover: a leaky EgressDecision seam, scope (net-new capabilities bundled with the refactor), the identity-less fail-open change, generation-pinning, and migration/operational gaps.

[johntmyers]

@maruiz93 Thanks for the detailed #1633 context. c18e06a now names host-local endpoints as a prospective consumer of these boundaries and keeps the local-routing and destination contracts extensible for that work. The technical design says this should be an explicit local-routing adapter or destination mode, not a general loopback or SSRF exemption; authorization must happen before the supervisor opens the host-loopback connector, and supported runtimes must advertise the capability. RFC 0005 intentionally does not choose reserved hostname versus endpoint flag or add the feature to its compatibility milestone, so those policy and driver details remain in separate #1633 feature design while reusing EgressIntent, adapter-specific responses, and the unopened connector boundary.

[pimlock]

Worth mentioning that the protocol enforcement is re-evaluated after the middleware, so the middleware cannot modify the request in a way that could bypass request policy (applicable to at least things like graphql, json-rpc, mcp).

[pimlock]

One datapoint on this - because of the overlapping endpoint metadata, I initially removed the ability to attach the middleware on the endpoint config.

Here's the context: #1738 (comment)

Excerpt

Why explicit policy/endpoint attachment was removed

OpenShell network policies are an additive bag of grants, not a hierarchy with one canonical winning rule. A request is allowed when at least one policy matches, and several policies may match the same request. Those policies may come from different sources: the user-authored base policy, provider-derived policy, or merged policy chunks/proposals.

That makes attachment semantics ambiguous. For example:

• Policy A allows a request and attaches middleware, while policy B also allows it without middleware. Should the middleware run?
• Policy A attaches chain [x] and policy B attaches [y]. Should OpenShell choose one, union them, reject the overlap, or invent cross-policy ordering?
• A broad provider-derived rule and a specific user rule may both admit the request. Neither is inherently the parent or winner.

Choosing the matched policy as the attachment source could also make enforcement depend on policy provenance or allow an overlapping grant without middleware to bypass a middleware-bearing grant.

[pimlock]

Actually I wonder if this could be an issue right now, if there are 2 endpoints, one with json-rpc protocol and another one raw, and the raw one may be selected ahead of the json-rpc one?

[pimlock]

[agent review]
Question about this mechanism:

and the TCP adapter recovers the original destination before building an intent

In order to map between the original DNS call and the connect(ip:port) there needs to be something to correlated between these 2.
E.g. the DNS lookup returns a synthetic IP, which then is used for connect and based on which we can find the mapping that was created during the DNS lookup. Potentially, the process identity could be used as well (DNS + later connect is from the same process).