Skip to content

Commit 4dcaa4d

Browse files
committed
docs(install): document the gateway endpoint for WSL 2 with Docker Desktop
Docker Desktop's host network is its own VM, so sandboxes cannot reach a gateway bound to loopback inside the WSL distribution and fail with ControlSupervisorStartFailed. Document the working configuration: keep the gateway on loopback and set the Docker driver grpc_endpoint to host.docker.internal. Link it from the Docker driver notes. Refs #3880 Signed-off-by: fede-kamel <fkamelhar@gmail.com>
1 parent c0eb3db commit 4dcaa4d

2 files changed

Lines changed: 15 additions & 1 deletion

File tree

‎docs/about/installation.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,20 @@ To keep the gateway running after you log out, enable linger:
102102
sudo loginctl enable-linger $USER
103103
```
104104

105+
### WSL 2 with Docker Desktop
106+
107+
Under Docker Desktop, the Docker host network is the Docker Desktop VM, not your WSL distribution, so sandboxes cannot reach a gateway on `127.0.0.1`. Sandbox creation then fails with `ControlSupervisorStartFailed`. Keep the gateway on its default loopback address and point the Docker driver at `host.docker.internal`, which Docker Desktop routes to the Windows host and WSL forwards to the distribution:
108+
109+
```toml
110+
[openshell]
111+
version = 2
112+
113+
[openshell.drivers.docker]
114+
grpc_endpoint = "https://host.docker.internal:17670"
115+
```
116+
117+
Add this to `~/.config/openshell/gateway.toml` and restart the gateway. Do not bind the gateway to the distribution's network address instead: Docker Desktop containers cannot route to it.
118+
105119
## Snap
106120

107121
The snap requires Docker Engine installed from your distribution or Docker's package repository. The Docker snap is not compatible.

‎docs/how-it-works/sandboxes/runtimes.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ socket_path = "/var/run/docker.sock"
9494

9595
Common options in `[openshell.drivers.docker]` are `socket_path`, `grpc_endpoint`, `sandbox_runtime_image`, `supervisor_image`, `image_pull_policy`, and `sandbox_pids_limit`. When `socket_path` is unset, the driver uses the socket found by auto-detection.
9696

97-
Docker Desktop must have host networking enabled, and it cannot use Enhanced Container Isolation. Set `grpc_endpoint` when sandboxes cannot reach the gateway on host loopback. For GPU sandboxes, configure Docker CDI before starting the gateway.
97+
Docker Desktop must have host networking enabled, and it cannot use Enhanced Container Isolation. Set `grpc_endpoint` when sandboxes cannot reach the gateway on host loopback. On WSL 2 with Docker Desktop, use `https://host.docker.internal:17670`; refer to [WSL 2 with Docker Desktop](/about/installation#wsl-2-with-docker-desktop). For GPU sandboxes, configure Docker CDI before starting the gateway.
9898

9999
### Docker Corporate Proxy Egress
100100

0 commit comments

Comments
 (0)