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

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

Signed-off-by: Drew Newberry <anewberry@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 and others added 16 commits July 29, 2026 22:57

feat(compute): query gateway listener requirements

5da41a6

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

feat(compute): add Podman listener requirements

6b51f12

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

test(docker): use default gateway bind address

11a60e3

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

fix(gateway): avoid wildcard primary listener

b1aeb29

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

fix(podman): validate callback listener discovery

46fea27

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

fix(server): support split dual-stack listeners

41afe8c

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

fix(podman): support legacy rootless listener discovery

5b03f5b

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

test(e2e): accept loopback plaintext rejection

0bbfe77

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

docs(agent): add callback listener diagnostics

54cdb79

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

fix(server): restrict compute callback listeners

92e8c0f

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

fix(podman): validate local callback port

cc03991

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

test(server): clarify callback listener contract

afb61c5

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

fix(podman): require pasta for local callbacks

816610a

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

docs(gateway): document RPM listener default

fbc9b8e

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

refactor(server): keep listener provenance diagnostic-only

f1c4137

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

fix(compute): preserve callback listener isolation

ea7c159

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

drew force-pushed the codex/gateway-callback-contract-poc-v2 branch from de1b4db to ea7c159 Compare July 30, 2026 06:04

drew added 7 commits July 29, 2026 23:27

test(e2e): remove Podman callback relay

d48bf0e

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

fix(packaging): preserve Podman callback loopback

aefdca0

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

ci(e2e): run VM smoke on nested-virt runner

0e1cd6b

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

ci(e2e): gate VM smoke on usable KVM

b372a94

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

ci(e2e): probe KVM through VM driver

aa289c1

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

ci(e2e): tolerate hosted KVM denial

b851aa3

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

chore: merge main into callback contract branch

6930be5

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

drew enabled auto-merge July 30, 2026 23:42

drew previously approved these changes Jul 30, 2026

View reviewed changes

test(server): close traced futures before assertions

c05a88d

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

drew dismissed their stale review via c05a88d July 31, 2026 00:32

revert: remove tracing test stabilization

580047a

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

drew approved these changes Jul 31, 2026

View reviewed changes

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

elezar commented Jul 27, 2026 •

edited

Loading