Repository navigation
refactor: align driver ownership of gateway callback listeners #1952
Description
Problem Statement
Docker can currently add gateway listener addresses from inside the in-process driver via gateway_bind_addresses(). Other drivers do not have that mechanism; they rely on gateway, operator, or deployment configuration to make the sandbox callback endpoint reachable.
This creates inconsistent ownership of gateway network exposure and does not extend cleanly to arbitrary remote compute drivers. A remote driver can inject a callback endpoint into its workloads, but it should not be expected to mutate gateway listeners over the compute-driver protocol.
The current model also weakens the local Podman posture. RPM defaults to bind_address = "0.0.0.0:17670" so sandbox containers can reach the gateway, even though a narrower listener on a Podman or Docker host-gateway interface would often be preferable.
Proposed Design
Expose gateway-owned extra listeners in gateway TOML, using the existing runtime concept already represented by Config.extra_bind_addresses:
[openshell.gateway]
bind_address = "127.0.0.1:17670"
extra_bind_addresses = ["172.18.0.1:17670"]These listeners should serve the same multiplexed gateway surface as bind_address.
Drivers should not decide what interfaces the gateway exposes. Drivers should only inject callback endpoint configuration into workloads. The operator or deployment owns making the callback endpoint route to one of the configured gateway listeners.
For example, a narrower Podman or Docker setup could use:
[openshell.gateway]
bind_address = "127.0.0.1:17670"
extra_bind_addresses = ["172.18.0.1:17670"]
[openshell.drivers.podman]
grpc_endpoint = "https://host.openshell.internal:17670"
host_gateway_ip = "172.18.0.1"Compatibility Plan
Phase this change to avoid surprising existing Linux Docker users:
- Add and document
[openshell.gateway].extra_bind_addresses. - Update Docker and Podman docs with narrow callback-listener examples that avoid broad
0.0.0.0binding when a host-gateway IP is known. - Keep Docker-derived
gateway_bind_addresses()temporarily for compatibility. - In a follow-up, decide whether Docker-derived listener mutation should be retained, warned, deprecated, or removed once explicit gateway config is established.
Remote Driver Contract
Remote drivers should not request gateway listener addresses through compute_driver.proto. The expected ownership model should be:
- Gateway owns listener addresses.
- Driver owns workload callback endpoint injection.
- Operator or deployment owns network reachability between the two.
If a future protocol capability is added, it should be explicit, startup-only, and allowlisted because binding unexpected gateway interfaces has security, certificate, and HA implications.
Definition of Done
- Add TOML schema support for
[openshell.gateway].extra_bind_addresses. - Preserve duplicate handling and listener merging with the primary
bind_address. - Add config parsing tests for extra listener addresses.
- Add server tests for listener address merging where appropriate.
- Document Docker and Podman examples that avoid broad
0.0.0.0binding. - Document that arbitrary remote drivers cannot request gateway listeners over the compute-driver protocol.
- Decide the compatibility path for Docker auto-derived listener addresses.
Metadata
Metadata
Assignees
Labels
Type
Projects
- Status
Activity
drew commentedon Jun 30, 2026
We should also detail how we intend to select
extra_bind_addresseswhen installing the gateway. I worry that this is going to be hard to configure because it is the driver that dictates what extra addresses we need to bind to.For example the VM doesn't need extra bind addresses at all. Docker on Mac vs Linux has different requirements, etc.
drew commentedon Jun 30, 2026
This doesn't seem correct. The current model enables us to strengthen the current podman posture. The podman driver just isn't using it.
On the flipside, this is going to create inconsistent ownership w.r.t configuring
extra_bind_addresses. These bind addresses are for better or worse an implementation detail of the compute driver.Why not?
elezar commentedon Jun 30, 2026
Thanks for the comments @drew. The original intent of this issue was to identify misalignment between the various drivers so as to simplify reasoning about their interactions with the gateway. I don't think the intial investigation captured all the subtleties and your questions below have definitely helped to iron things out a bit.
Yes, this was incorrectly stated. Let me update it.
I think the issue here is that when originally formulating the issue we focussed on
extra_bind_addressesas the solution since the field already existed in theConfigstruct. The fact is that it is actually unused and we can acheive what we want for Docker using the already present Driver-specifichost_gateway_ip.Since we now support external / third-party drivers, we may not be able to blindly accept suggested bind addresses. Or according to Claude:
elezar commentedon Jun 30, 2026
@/tmp/c1952.md
[-]refactor: make sandbox callback listeners gateway-owned[/-][+]refactor: align driver ownership of gateway callback listeners[/+]