docs(rfc): propose sandbox service exposure architecture

[drew]

Summary

RFC 0017 proposes a dedicated application listener on supervisors so sandbox HTTP and WebSocket traffic can bypass the gateway and its control connection. This lets operators scale application ingress and configure its access policies separately from gateway management.

The gateway continues to manage service declarations and publishes supervisor-advertised routes through authenticated discovery. Operators can integrate existing ingress with that discovery or use the optional openshell-sandbox-proxy as a reference implementation.

Design

• Make the supervisor app listener the core feature, with hostname routing to sandbox services under each sandbox's policy.
• Support Kubernetes ingress plus a discovery adapter routing to supervisor Services.
• Accommodate future shared supervisors while preserving distinct sandbox policies.
• Preserve existing service commands and gateway routing for simple deployments.
• Leave TLS termination, ingress policy, discovery authorization, and route lifecycle details open for review.

Validation

• Repository Markdown lint passes.
• Diff whitespace checks pass.
• RFC-only change; no runtime implementation.

Related issue

Closes #4266

Related work

• feat: sandbox ingress — expose services from inside the network namespace #994 and Support Kubernetes-native Service/Endpoint exposure for sandbox agents #1791: service declarations, supervisor enforcement, and Kubernetes-native exposure.
• feat(gateway): separate control-plane and service-ingress listeners #4210 / feat(gateway): separate control-plane and service-ingress listeners #4213: separate gateway listeners, an alternative that retains gateway payload traffic.
• Option to pass through external Authorization headers without replacement #1794 and feat: expose sandbox services during creation #3402: bearer authentication and create-time exposure workflows to preserve.
• feat(services): continuously observe HTTP application readiness #4229: service readiness, kept distinct from route authorization.
• feat(helm): support agentgateway ingress #2469 and feat(helm): support shared agentgateway Gateway #3715: dedicated/shared ingress integrations that could use supervisor listeners and discovery.

[rrhubenov]

Thank you for the doc, leaving some diagrams that might help with discussions:
Option 1

Option 2

Option 3

Discussed this with @kon-angelo and @dimityrmirchev, our opinion is that option 3 fits the best in a k8s environment specifically. Existing k8s clusters have their networking configured using k8s primitives, so having a proxy being created by OpenShell might not be desired by operators of the clusters on which it is deployed.

During a talk with @drew and @johntmyers, we came to the conclusion that Option 1 (the additional proxy component setup) can be implemented in such a way so that the proxy (and most likely the services) can be an optional component. This way, operators can decide easily between Option 1 and Option 3.

[TaylorMutch]

Picking this RFC up from @drew, I'll be pushing an update to this branch that includes the feedback from @rrhubenov and the community call.

[rrhubenov]

@TaylorMutch I spent a bit of time on the RFC and I think it generally looks great! :)
I'd just like to do one more pass over it, specifically focusing on the TLS aspect of the implementation. I'll also try to give my input on all the open questions as well.

[rrhubenov]

Leaving some additional feedback here, can leave it on the implementation PR as well when it gets created.

In a kubernetes context, cluster administrators often terminate TLS at different points in the cluster, e.g.:

• in the cloud load balancer, even before the cluster
• at the edge, using the ingress controller (e.g. nginx)
• using a service mesh with sidecars, where every connection is terminated and rewrapped between pods, mTLS

So terminating TLS at the supervisor might cause friction with these setups.
The RFC mentions terminating TLS at the edge, I'd say making that the default might land better