feat(gateway): separate control-plane and service-ingress listeners

[mrunalp]

Summary

Allow operators to expose sandbox applications on a separate gateway listener while restricting privileged control-plane access to the primary listener. Shared-port routing remains the default.

Related Issue

Closes #4210

Changes

• Add optional service_bind_address, --service-port / OPENSHELL_SERVICE_PORT, and Helm service.ingressPort, with port-conflict validation at startup and preflight.
• Support external ingress port mappings with service_public_port, Helm service.ingressNodePort, and service.ingressPublicPort. A fixed ingress NodePort is advertised automatically; automatically allocated NodePorts must be queried and configured explicitly.
• Serve application HTTP and WebSockets on dedicated ingress without exposing gateway RPC, authentication, or gateway tunnel routes. Reuse server TLS certificates without requesting control-plane client certificates, including after certificate reload.
• Regenerate URL fields in durable CreateSandbox and ExposeService replays from current configuration for all API clients, preserving the original resource identities and service names. Advertise the reachable service port in gRPC metadata so updated CLI output does not substitute the control-plane port.
• Update configuration documentation, the gateway man page, chart documentation, and the public CLI and cluster debugging skills. Document the CLI upgrade and network routing changes required before enabling the split.

Testing

• Gateway library tests: 1,975 passed, 8 ignored, including socket routing boundaries, service TLS without client certificates, durable replays after configuration changes, public URL ports, and advertised gRPC metadata.
• CLI lifecycle integration tests: 45 passed, 2 ignored, including actual CLI JSON output for direct ingress and an external port mapping; focused URL tests: 8 passed on the initial implementation.
• Core configuration tests: 30 passed.
• All-target Clippy for core, server, CLI, and gateway with warnings denied; Rust formatting and diff checks.
• Full repository pre-commit checks, including workspace, sandbox performance-feature, E2E crate, and example Clippy; lockfiles, licenses, Python/TypeScript/protobuf lint, and Markdown checks.
• Helm tests: 280 passed across gateway and workspace charts; Helm lint/render variants and generated chart documentation checks.
• Published documentation validation: no errors (three warnings), navigation check passed.
• Live Kubernetes E2E: attempted through e2e/rust/e2e-kubernetes.sh; the wrapper stopped before deployment because Docker is not running and no cluster context is configured. Live E2E verification remains pending.
• Required GitHub CI: NVIDIA runner workflows require maintainer vetting/mirroring of the current commit before they can run.

For OCE rollout, enable service.ingressPort, update network.providerHarness, and restrict Agent Gateway access to the ingress port. Upgrade older CLIs before enabling the split because they still rewrite service URLs to the control-plane port.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Relevant configuration documentation and skills updated

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

Label test:e2e applied, but pull-request/4213 does not exist yet. A maintainer needs to comment /ok to test a4210a990dbbd715e4a803cef2caa344d6f1eabb to mirror this PR. Once the mirror exists, re-apply the label or re-run Branch E2E Checks from the Actions tab.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4213.docs.buildwithfern.com/openshell

[russellb]

agent review that I sent mrunalp via slack earlier, just for the record:

---

Reviewed [#4213](#4213) at a4210a9. The listener split addresses OCE’s isolation requirement when enabled. The dedicated listener exposes application HTTP/WebSockets without gRPC, auth routes, or the control-plane WebSocket tunnel.

I found two compatibility gaps:

• Retried API requests can return unusable URLs after enabling the split. A previously successful CreateSandbox or ExposeService request retains its original URL in the durable replay record. Retrying the same request_id after moving services returns the old control-plane port, which now rejects service traffic. The new metadata corrects this only for the updated CLI; other clients still receive stale response fields. Regenerate service URLs using current configuration during replay. See [replay handling](

  OpenShell/crates/openshell-server/src/grpc/mutation_replay/ordinary.rs

  Line 451 in a4210a9

  scoped_mutation!(

  ) and [metadata workaround](

  OpenShell/crates/openshell-server/src/multiplex.rs

  Line 285 in a4210a9

  // Add this outside typed dispatch so durable mutation replays also

  ).
• Externally remapped ingress ports produce incorrect printed URLs. Previously, the CLI used the registered gateway’s external port. With dedicated ingress, it always substitutes the internal listener port. For example, ingress on 8082 exposed through a NodePort will print :8082 instead of the allocated external port. The chart provides no ingress NodePort override or advertised external endpoint. This should be supported or explicitly accepted as a limitation; direct in-cluster OCE access avoids it. See [URL rewriting](

  OpenShell/crates/openshell-cli/src/run.rs

  Line 4382 in a4210a9

  let port = if let Some(port) = dedicated_service_port {

  ), [Service template](

  OpenShell/deploy/helm/openshell/templates/service.yaml

  Line 21 in a4210a9

  {{- if .Values.service.ingressPort }}

  ), and [NodePort behavior](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport).

The rollout needs coordination:

• Shared-port behavior remains the default. OCE must set service.ingressPort, update network.providerHarness, and restrict Agent Gateway access to that port.
• Older CLIs still rewrite service URLs to the control-plane port; upgrade them before enabling the split.
• Dedicated ingress deliberately stops requiring control-plane client certificates. The [public CLI skill](

  OpenShell/skills/openshell-cli/SKILL.md

  Line 919 in a4210a9

  bypass control-plane RPC authorization, but they still use the gateway's

  ) still says service traffic inherits that requirement and needs updating.

I ran 266 gateway Helm tests—all passed—and reproduced the URL rewriting behavior. I did not rerun the Rust suite or live Kubernetes isolation tests; required CI checks remain pending. Our local implementation is untouched.

[mrunalp]

/ok to test 914000a