@@ -41,9 +41,9 @@ mediates every supported TCP and DNS operation, attributes it to the calling
 binary, and sends the request across the private channel. The supervisor
 authorizes the request before it opens an upstream connection. Docker's absent
 workload network is the mandatory outer fence if mediation fails or is
-bypassed. The trusted supervisor companion uses Docker host networking, where
-it reaches the gateway's primary loopback listener and originates approved
-egress.
+bypassed. The trusted supervisor companion originates approved egress. Its
+operator-owned `supervisor_network_mode` defaults to `host`. Set `bridge` to
+run the supervisor on Docker's bridge network; `auto` also selects host.
 
 The driver copies trusted runtime bytes from the configured supervisor image
 through the Docker archive API. No workload launch depends on a host bind
@@ -158,7 +158,7 @@ openshell sandbox create \
 `/openshell-sandbox` binary. The driver extracts that binary as bytes and
 stages it into the stopped workload. `supervisor_image` contains the
 dynamically linked glibc `/openshell-supervisor` binary that runs in the
-host-networked supervisor container. Release and gateway image builds bake
+supervisor companion container. Release and gateway image builds bake
 matching image tags into the binary.
 
 ## Gateway session and TLS
@@ -172,7 +172,7 @@ When no endpoint is configured, the supervisor connects to
 Docker daemon host. A configured HTTPS server certificate must include the
 endpoint host in its subject alternative names.
 
-The driver publishes host loopback as the backend address for
+In host mode, the driver publishes host loopback as the backend address for
 `host.openshell.internal`. Policy DNS resolves that reserved name through the
 mediated path, so policies can reach host services without a Docker bridge,
 container DNS alias, or another gateway listener.
@@ -181,9 +181,33 @@ For HTTPS endpoints, the supervisor receives only the gateway CA and
 uses its sandbox-scoped bearer token to authenticate RPCs. User client
 certificates and private keys are not delivered to either container.
 
-Docker Engine on Linux supports host networking directly. Docker Desktop
-requires host networking to be enabled in Settings and does not support it
-when Enhanced Container Isolation is enabled.
+Host mode on Docker Desktop requires host networking enabled in Settings.
+For bridge mode or a gateway endpoint using `host.docker.internal`, the driver
+resolves Docker's `host-gateway` once during initialization and caches it.
+A temporary container runs `--help` from the immutable supervisor image with
+no network, no capabilities, no privilege escalation, and a read-only root
+filesystem. The driver downloads Docker's generated `/etc/hosts` through the
+archive API, preferring a unique IPv4 address and otherwise a unique IPv6
+address. Resolution has a 30-second timeout; forced cleanup has a separate
+10-second timeout and runs after success or failure.
+
+The driver uses the selected address for both host aliases and the runtime
+descriptor's trust pin; workload DNS and hosts files cannot select it. Host
+mode with other gateway endpoints retains its gateway-address pin. An explicit
+operator-owned `host_gateway_ip` overrides discovery and skips the temporary
+container. No supervisor changes or per-sandbox discovery are required.
+
+When `grpc_endpoint` is omitted, bridge mode uses `host.docker.internal` on
+Desktop or for a wildcard gateway listener, and the concrete bind address for
+other non-loopback Linux listeners. The port is the gateway bind port; remapped
+container publications require an explicit endpoint. Native Linux loopback-only
+listeners cannot serve a bridge supervisor and produce an actionable error.
+Explicit endpoints retain TLS verification and are never rewritten; bridge
+rejects loopback/unspecified endpoint addresses. Host services bound only to
+loopback are also unreachable from a native Linux bridge supervisor.
+
+The selected network mode does not change the sandbox's mandatory Landlock
+and seccomp qualification.
 
 The supervisor owns these security-critical variables: