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, rootless
slirp4netns callback support, and operator-configurable or
interceptor-extensible listener capabilities remain follow-up work.

Related Issue

Related to #2215

Depends on #2542

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 the listener authorization scope through connection dispatch and
request extensions, while keeping driver/reason provenance in listener
binding diagnostics.
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 the Docker managed-bridge listener to an authorized exact requirement.
Add Podman discovery for rootful Linux bridges, rootless pasta
default-route interfaces, Podman Machine IPv4 loopback, and explicit Linux
host_gateway_ip.
Fail startup for local rootless Podman callbacks when the helper is
slirp4netns, unknown, or unreported. An explicitly remote grpc_endpoint
remains supported for those environments.
Require Podman 5.x for supported rootless local callbacks and remove the
Ubuntu 24.04/Podman 4 rootless E2E case until slirp4netns support is added.
Request no additional listener for explicitly remote Podman callback URIs,
and fail startup when a required local callback listener cannot be safely
discovered.
Reject local Podman callback aliases whose effective URI port differs from
the gateway primary listener, while permitting arbitrary remote ports.
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

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

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

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

/ok-to-test c768219

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

/ok-to-test a5cef7d

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

-# 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 · 2026-07-29T08:46:01Z

/ok-to-test 18044d2

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: 18044d2ddaaab25063fa2f2be7adcbd65c03ec4a

Review findings:

Two warning-level findings are left inline: the Podman callback discovery docs still describe only pasta, and the startup listener log still omits listener purpose/provenance.
General warning: docs/reference/gateway-config.mdx is not in the current diff, but it still needs a 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.

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

Next state: gator:in-review

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: 1394c1e0d54a0c546e889ccaf9ba9ad55533871f

Review findings:

One warning-level finding was left inline: Podman bridge gateway inspection is now mandatory during startup even for callback topologies that do not need the bridge address.

Docs: Fern docs and companion troubleshooting guidance were updated for the primary listener default and callback-only listener behavior.

Tests: I did not run local tests. Current GitHub checks are still pending, including OpenShell / E2E and some package build jobs.

Next state: gator:in-review

elezar · 2026-07-29T13:47:35Z

-            .network_gateway_ip(&config.network_name)
-            .await
-            .unwrap_or(None);
+        let network_gateway_ip = client.network_gateway_ip(&config.network_name).await?;


gator-agent

Warning: network_gateway_ip() is now mandatory during every Podman driver startup, before the driver knows whether the callback endpoint actually needs the Podman bridge address. This regresses explicitly remote grpc_endpoint configurations, and also rootless pasta without host_gateway_ip, where listener discovery uses the host default-route source instead of the Podman bridge gateway. Keep this inspection best-effort at construction time and fail later only when gateway_listener_requirements() needs the exact bridge address. For example, restore a guarded fallback here:

let network_gateway_ip = match client.network_gateway_ip(&config.network_name).await { Ok(gateway_ip) => gateway_ip, Err(err) => { warn!( network = %config.network_name, error = %err, "Podman bridge gateway inspection failed; exact local callback listeners may be unavailable" ); None } };

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: 3dedd40ec1ddd7dc4935a8673d7f21df017f68cc

Review findings:

No blocking findings remain from the independent code-only review for this head. The previous docs, gateway-config, listener provenance, and Podman bridge-inspection findings appear resolved.

Docs: Fern docs, RPM/operator docs, and troubleshooting guidance were updated for the primary listener default and callback-only listener behavior.

Tests: I did not run local tests. GitHub Branch Checks currently include a macOS Rust toolchain setup failure while installing Clippy, and test:e2e pipeline jobs are still pending.

Next state: gator:watch-pipeline

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: bcef4ca7e352589d2db5d2eb0df9c447c1907ef5

Review findings:

One warning-level finding is left inline: Podman driver startup still makes bridge gateway inspection mandatory even when the selected callback topology does not need that bridge address.

Docs: Fern docs, RPM/operator docs, and companion troubleshooting guidance were updated for the primary listener default and callback-only listener behavior.

Tests: I did not run local tests. Current GitHub checks are still pending, including OpenShell / Branch Checks and OpenShell / E2E.

Next state: gator:in-review

elezar · 2026-07-29T15:37:34Z

-            .network_gateway_ip(&config.network_name)
-            .await
-            .unwrap_or(None);
+        let network_gateway_ip = client.network_gateway_ip(&config.network_name).await?;


gator-agent

Warning: network_gateway_ip() is still mandatory during Podman driver construction even when the selected callback topology does not need the bridge gateway address, such as an explicitly remote grpc_endpoint, macOS loopback forwarding, or rootless pasta without host_gateway_ip. Startup should fail when a required local callback listener cannot be discovered, not when unused bridge inspection fails. Move auto-detected grpc_endpoint setup before gateway-IP inspection and only call network_gateway_ip() for Linux local-alias cases that will use an exact bridge bind, such as rootful Podman with empty host_gateway_ip.

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

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 5 times, most recently from c2543d9 to e817863 Compare July 28, 2026 08:55

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 a team, derekwaynecarr, maxamillion and mrunalp as code owners July 28, 2026 11:47

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

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch from ee88761 to 18044d2 Compare July 29, 2026 08:45

elezar mentioned this pull request Jul 29, 2026

feat(gateway): use an explicit callback-only endpoint for local sandboxes #2538

Open

12 tasks

elezar commented Jul 29, 2026

View reviewed changes

Comment thread docs/reference/sandbox-compute-drivers.mdx Outdated

Comment thread crates/openshell-server/src/lib.rs Outdated

elezar commented Jul 29, 2026

View reviewed changes

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch from 1394c1e to 3dedd40 Compare July 29, 2026 14:22

elezar changed the base branch from main to codex/gateway-listener-refactor July 29, 2026 14:23

elezar commented Jul 29, 2026

View reviewed changes

elezar added gator:watch-pipeline Gator is monitoring PR CI/CD status gator:in-review Gator is reviewing or awaiting PR review feedback and removed gator:in-review Gator is reviewing or awaiting PR review feedback gator:watch-pipeline Gator is monitoring PR CI/CD status labels Jul 29, 2026

elezar mentioned this pull request Jul 29, 2026

ci(e2e): probe VM gateway readiness #2544

Open

6 tasks

elezar force-pushed the codex/gateway-listener-refactor branch from 26dd8a8 to a8b41f9 Compare July 29, 2026 15:23

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch from 3dedd40 to bcef4ca Compare July 29, 2026 15:28

elezar commented Jul 29, 2026

View reviewed changes

elezar added gator:blocked Gator is blocked by process or repository gates and removed gator:in-review Gator is reviewing or awaiting PR review feedback labels Jul 29, 2026

elezar added 15 commits July 29, 2026 18:31

feat(compute): query gateway listener requirements

36a2915

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

feat(compute): add Podman listener requirements

8560560

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

test(docker): use default gateway bind address

508523f

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

fix(gateway): avoid wildcard primary listener

7e5986f

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

fix(podman): validate callback listener discovery

9157c06

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

fix(server): support split dual-stack listeners

dc6c4eb

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

fix(podman): support legacy rootless listener discovery

3f9d2f2

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

test(e2e): accept loopback plaintext rejection

cfbf5b7

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

docs(agent): add callback listener diagnostics

aba0e31

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

fix(server): restrict compute callback listeners

4c2d3ef

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

fix(podman): validate local callback port

6cd64cb

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

test(server): clarify callback listener contract

f4f6e8d

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

fix(podman): require pasta for local callbacks

7687dde

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

docs(gateway): document RPM listener default

24502bf

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

refactor(server): keep listener provenance diagnostic-only

352683d

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

elezar force-pushed the codex/gateway-callback-contract-poc-v2 branch from bcef4ca to 352683d Compare July 29, 2026 16:40

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!

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 commented Jul 29, 2026

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

Uh oh!

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

elezar Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

PR Review Status

Uh oh!

elezar Jul 29, 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