feat(compute): negotiate gateway callback listeners by elezar · Pull Request #2492 · NVIDIA/OpenShell

elezar · 2026-07-27T12:30:27Z

Summary

Add a shared, gateway-owned contract for built-in compute drivers to report the
additional listeners required by their sandbox callback topology. Migrate
Docker and Podman to that contract so the primary gateway listener can remain
on its loopback default.

This PR is the production-scoped listener-discovery portion of #2215. It keeps
the initial authorization ceiling limited to the built-in Docker and Podman
topologies. Negotiated listeners expose only the generated sandbox-callable
gRPC surface; the operator-configured primary listener retains the full
multiplexed API.

Per-sandbox callback URI delivery, portable credential delivery, and
operator-configurable or interceptor-extensible listener capabilities remain
follow-up work.

Related Issue

Related to #2215

Changes

Add ComputeDriver.GetGatewayListenerRequirements with exact-address and
semantic default-route/IPv4-loopback selectors.
Treat UNIMPLEMENTED from older external drivers as no additional listener
requirements for protocol compatibility.
Validate, authorize, resolve, deduplicate, and bind requested listeners in
the gateway before persisted sandboxes resume.
Preserve listener purpose and provenance through connection dispatch and
request extensions.
Restrict compute-driver callback listeners to sandbox-callable gRPC methods
before normal authentication and routing.
Reject user/admin APIs, health, reflection, non-callback inference APIs, and
HTTP routes on callback listeners while leaving primary routing unchanged.
Migrate Docker's managed-bridge listener to an authorized exact requirement.
Add Podman discovery for rootful Linux bridges, rootless pasta default-route
interfaces, rootless slirp4netns and legacy Podman 4 compatibility, Podman
Machine IPv4 loopback, and explicit Linux host_gateway_ip.
Request no additional listener for explicitly remote Podman callback URIs,
and fail startup when a required local callback listener cannot be safely
discovered.
Support split IPv4/IPv6 listeners on the same port by making the IPv6
wildcard socket IPv6-only when necessary.
Keep the primary listener on its loopback default in Docker E2E, RPM/Podman
configurations, and the local rootless-Podman development launcher.
Update gateway architecture, operator docs, Podman networking notes, and
cluster diagnostics.

Testing

cargo test -p openshell-driver-podman (136 tests)
cargo test -p openshell-server --lib (1,127 tests)
Four focused callback-listener routing regressions
Focused server and Podman Clippy across all targets with warnings denied
Rust formatting and Markdown/Mermaid linting
Unit and regression coverage for listener authorization, Podman discovery
failures, remote callbacks, IPv4 loopback selection, split-dual-stack
binding, callback-only routing, and unchanged primary-listener behavior
Previous mirrored Branch Checks, Helm Lint, Python, Docker, rootless
Podman 4 and 5, Kubernetes, VM, and MCP E2E
Updated mirrored CI for the callback-only listener commit

The full workspace pre-commit gate reaches an unrelated macOS-only unused
Ordering import already present on the branch base; #2513 contains that
independent fix. All other pre-commit tasks completed successfully. Docker and
live Podman E2E were not run locally.

Checklist

Follows Conventional Commits
Commits are signed off (DCO)
Architecture and relevant user-facing documentation updated

copy-pr-bot · 2026-07-27T12:30:30Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

github-actions · 2026-07-27T12:31:15Z

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

elezar · 2026-07-27T12:31:24Z

/ok-to-test 7e8b6d2

elezar · 2026-07-27T12:52:52Z

/ok-to-test ec3d9eb

Signed-off-by: Evan Lezar <elezar@nvidia.com>

github-actions · 2026-07-28T08:56:12Z

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

elezar · 2026-07-28T09:50:38Z

/ok-to-test e817863

elezar · 2026-07-28T10:17:26Z

/ok to test

Signed-off-by: Evan Lezar <elezar@nvidia.com>

elezar · 2026-07-28T10:29:26Z

/ok-to-test c768219

Signed-off-by: Evan Lezar <elezar@nvidia.com>

elezar · 2026-07-28T10:32:49Z

/ok-to-test a5cef7d

Signed-off-by: Evan Lezar <elezar@nvidia.com>

elezar · 2026-07-28T14:32:22Z

/ok-to-test ee88761

elezar

gator-agent

PR Review Status

Validation: This maintainer-authored PR is project-valid and directly advances the listener-discovery work related to #2215.
Head SHA: ee8876193e2191b948b470abf592ce9d3b32357e

Review findings:

Three warning-level findings were left inline: one docs accuracy issue, one gateway config reference-doc gap, and one operational logging gap.

Docs: Updated in part, but the published Podman and gateway configuration docs still need the inline corrections before gator can move this to pipeline watch.

Next state: gator:in-review

elezar · 2026-07-28T16:03:01Z

 For proxy-required networks, the Podman driver also accepts the corporate egress proxy keys `https_proxy`, `no_proxy`, `proxy_auth_file`, `proxy_auth_allow_insecure`, and `proxy_connect_by_hostname`. The supervisor chains policy-approved TLS tunnels through the proxy with HTTP CONNECT instead of dialing destinations directly. See the [Gateway Configuration File](./gateway-config) reference for the full contract, including the cleartext-credential acknowledgement and the validated-IP CONNECT behavior.

-On macOS with `podman machine`, the driver uses gvproxy's host-loopback IP, `192.168.127.254`, for sandbox host aliases by default. Set `host_gateway_ip` only when your Podman machine uses a non-standard host-loopback address. On Linux, an empty `host_gateway_ip` keeps Podman's `host-gateway` resolver behavior.
+On macOS with `podman machine`, the driver uses gvproxy's host-loopback IP, `192.168.127.254`, for sandbox host aliases by default. Set `host_gateway_ip` only when your Podman machine uses a non-standard host-loopback address. On Linux, an empty `host_gateway_ip` keeps Podman's `host-gateway` resolver behavior. Automatic local callback listener discovery for rootless Podman requires the default pasta network helper. When Podman reports another helper, set `host_gateway_ip` or configure an explicitly remote `grpc_endpoint`; otherwise the gateway fails startup rather than leaving sandbox callbacks unreachable.


gator-agent

Warning: This published Podman docs paragraph still says rootless callback discovery requires the default pasta helper, but the implementation now accepts pasta, slirp4netns, and the empty legacy Podman helper. Please update this paragraph so supported users are not incorrectly told to configure host_gateway_ip or a remote grpc_endpoint.

elezar · 2026-07-28T16:03:01Z

-# you don't use Podman or want loopback-only access (e.g. behind a reverse
-# proxy). mTLS is enabled by default and protects all connections.
-bind_address = "0.0.0.0:17670"
+# Keep the primary listener on the built-in 127.0.0.1:17670 default. The


gator-agent

Warning: This changes the RPM config default by removing the bind_address = "0.0.0.0:17670" override, but docs/reference/gateway-config.mdx was not updated. Please add a short note that RPM/Podman leaves bind_address unset, uses the built-in 127.0.0.1:17670 primary listener, and relies on restricted driver-negotiated callback listeners.

elezar · 2026-07-28T16:03:01Z

-        let local_addr = listener.local_addr().unwrap_or(address);
+            .map_err(|e| Error::transport(format!("failed to bind to {}: {e}", spec.address)))?;
+        let local_addr = listener.local_addr().unwrap_or(spec.address);
        info!(address = %local_addr, "Server listening");


gator-agent

Warning: The troubleshooting skill now tells operators to inspect the listener-purpose startup log, but this startup log still emits only address. Please include purpose = ?spec.purpose here so unexpected callback binds show the driver and reason in gateway logs.

elezar added the test:e2e Requires end-to-end coverage label Jul 27, 2026

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch from 7e8b6d2 to ec3d9eb Compare July 27, 2026 12:39

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch 4 times, most recently from e0ba998 to c2543d9 Compare July 27, 2026 16:02

elezar added 7 commits July 28, 2026 10:22

refactor(server): preserve gateway listener purpose

c1ac10d

Signed-off-by: Evan Lezar <elezar@nvidia.com>

feat(compute): query gateway listener requirements

8a958b7

Signed-off-by: Evan Lezar <elezar@nvidia.com>

feat(compute): add Podman listener requirements

630f0de

Signed-off-by: Evan Lezar <elezar@nvidia.com>

test(docker): use default gateway bind address

9a15fc7

Signed-off-by: Evan Lezar <elezar@nvidia.com>

fix(gateway): avoid wildcard primary listener

43ac0cf

Signed-off-by: Evan Lezar <elezar@nvidia.com>

fix(podman): validate callback listener discovery

df6998f

Signed-off-by: Evan Lezar <elezar@nvidia.com>

fix(server): support split dual-stack listeners

e817863

Signed-off-by: Evan Lezar <elezar@nvidia.com>

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch from c2543d9 to e817863 Compare July 28, 2026 08:55

elezar added 2 commits July 28, 2026 12:28

fix(podman): support legacy rootless listener discovery

9ef1670

Signed-off-by: Evan Lezar <elezar@nvidia.com>

test(e2e): accept loopback plaintext rejection

c768219

Signed-off-by: Evan Lezar <elezar@nvidia.com>

docs(agent): add callback listener diagnostics

a5cef7d

Signed-off-by: Evan Lezar <elezar@nvidia.com>

elezar mentioned this pull request Jul 28, 2026

feat(driver-oci): add OCI compute driver #2312

Open

6 tasks

elezar marked this pull request as ready for review July 28, 2026 11:47

elezar requested review from maxamillion and mrunalp as code owners July 28, 2026 11:47

elezar requested review from a team and derekwaynecarr as code owners July 28, 2026 11:47

fix(server): restrict compute callback listeners

ee88761

Signed-off-by: Evan Lezar <elezar@nvidia.com>

elezar changed the title ~~refactor(compute): prototype gateway listener requirements~~ feat(compute): negotiate gateway callback listeners Jul 28, 2026

elezar commented Jul 28, 2026

View reviewed changes

elezar added the gator:in-review Gator is reviewing or awaiting PR review feedback label Jul 28, 2026

Uh oh!

Conversation

elezar commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Testing

Checklist

Uh oh!

copy-pr-bot Bot commented Jul 27, 2026

Uh oh!

github-actions Bot commented Jul 27, 2026

Uh oh!

elezar commented Jul 27, 2026

Uh oh!

elezar commented Jul 27, 2026

Uh oh!

github-actions Bot commented Jul 28, 2026

Uh oh!

elezar commented Jul 28, 2026

Uh oh!

elezar commented Jul 28, 2026

Uh oh!

elezar commented Jul 28, 2026

Uh oh!

elezar commented Jul 28, 2026

Uh oh!

elezar commented Jul 28, 2026

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

elezar Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

elezar Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

elezar commented Jul 27, 2026 •

edited

Loading