bug(docker): trusted host alias is unavailable with Docker Desktop gateway endpoint #4403

User Story

I use OpenShell on an Apple Silicon Mac with Docker Desktop to run a sandbox that must reach an explicitly policy-approved service on the Mac through host.openshell.internal. I directly encountered a sandbox that reached Ready after configuring the documented Docker Desktop gateway endpoint, but OpenShell refused the approved host connection because it had no trusted host-gateway address. This blocks the sandbox workload even though its policy allows the exact host and port.

Problem Statement

On Docker Desktop, setting the Docker driver's grpc_endpoint to https://host.docker.internal:<gateway-port> lets the supervisor reach a Mac-hosted gateway without Docker Desktop host networking. However, the Docker driver does not provide a concrete trusted address for host.openshell.internal when the endpoint uses that hostname. The supervisor therefore refuses policy-approved host traffic with policy_dns_trusted_gateway_unavailable.

This is the host-service limitation documented by #3924 after the gateway-connectivity failure in #3880. It is distinct from the supervisor reaching the OpenShell gateway: sandbox creation succeeds, but the running sandbox cannot use an explicitly allowed Mac-hosted service.

Impact / Why This Matters

Users must currently choose between enabling Docker Desktop host networking and retaining the loopback endpoint, or using host.docker.internal so sandboxes start but losing policy-mediated access to host services. The second state is misleading because the sandbox reaches Ready; the host-service failure appears only when the workload tries to connect.

The workaround of enabling Docker Desktop host networking changes a global Docker Desktop setting and is not always available on managed Macs. Using an unpinned DNS result would weaken the trusted-gateway boundary and is not an acceptable workaround.

Acceptance Criteria

• With the Docker driver endpoint set to https://host.docker.internal:<gateway-port>, a sandbox can reach an exact host.openshell.internal:<allowed-port> endpoint allowed by its network policy on Docker Desktop.
• The supervisor receives one concrete Docker-engine-owned host-gateway address; missing, ambiguous, malformed, multicast, unspecified, broadcast, or metadata addresses fail closed.
• Resolution does not add capabilities, host networking, writable root filesystems, or a DNS-trust fallback.
• Temporary resolution resources are installation-scoped and removed after success or failure.
• Existing literal and loopback endpoint behavior remains unchanged.
• Focused unit coverage and a live Docker Desktop check protect the behavior.

Reproduction Steps

1. On macOS with Docker Desktop host networking disabled, run an OpenShell gateway using the Docker driver with:

   [openshell.drivers.docker]
   grpc_endpoint = "https://host.docker.internal:17670"

2. Start a loopback host test service on a chosen port using software already present on the development Mac.

3. Create an OpenShell sandbox whose network policy allows only host.openshell.internal:<chosen-port>.

4. Connect to that endpoint from the sandbox.

5. Observe that the sandbox reaches Ready, but the supervisor refuses the connection with:

   NET:REFUSE [MED] DENIED host.openshell.internal [reason:policy_dns_trusted_gateway_unavailable]
   

Suggested UX

No new command or configuration is required. The existing configuration and policy should work:

[openshell.drivers.docker]
grpc_endpoint = "https://host.docker.internal:17670"

network_policies:
  host-service:
    endpoints:
      - host: host.openshell.internal
        port: 10443

Environment

• OpenShell: v0.1.3
• OS: macOS 26.7.1 (25G241), Apple Silicon
• Docker Desktop engine: 29.8.0, Linux arm64 engine
• Deployment: local OpenShell gateway with the Docker compute driver and mTLS
• Related work: bug(docker): sandboxes never become Ready on WSL 2 + Docker Desktop (supervisor dials 127.0.0.1) #3880 and fix(docker): reach a WSL 2 gateway through Docker Desktop's host alias #3924

Logs

NET:REFUSE [MED] DENIED host.openshell.internal [reason:policy_dns_trusted_gateway_unavailable]