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.0 binding 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
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: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:
Compatibility Plan
Phase this change to avoid surprising existing Linux Docker users:
[openshell.gateway].extra_bind_addresses.0.0.0.0binding when a host-gateway IP is known.gateway_bind_addresses()temporarily for compatibility.Remote Driver Contract
Remote drivers should not request gateway listener addresses through
compute_driver.proto. The expected ownership model should be: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
[openshell.gateway].extra_bind_addresses.bind_address.0.0.0.0binding.