bug(docker): sandboxes never become Ready on WSL 2 + Docker Desktop (supervisor dials 127.0.0.1)

[fede-kamel]

User Story

As a developer on Windows using WSL 2 with Docker Desktop (listed as an experimental platform in the support matrix), I want a default local install to create a working sandbox, so I can follow the quickstart without reverse-engineering the Docker driver's networking.

Problem Statement

With the gateway running as the default systemd user service inside the WSL distro (bound to 127.0.0.1:17670) and Docker Desktop providing the engine, every openshell sandbox create fails:

ControlSupervisorStartFailed: Docker supervisor exited before becoming ready
... Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server

The Docker driver defaults grpc_endpoint to https://127.0.0.1:<port> and runs the supervisor container with network_mode: host. Under Docker Desktop, the host network is the Docker Desktop VM, not the WSL distro, so the supervisor never reaches the gateway.

What I tried:

• A --network host container calling https://127.0.0.1:17670 gets connection refused.
• Binding the gateway to the distro's eth0 address (WSL NAT mode) and pointing grpc_endpoint at it also fails: Docker Desktop containers can't route to the distro address.
• Working configuration: keep the gateway on 127.0.0.1 (WSL forwards loopback listeners to Windows), and set the Docker driver endpoint to host.docker.internal. The generated server certificate already includes a host.docker.internal SAN, and for a non-localhost hostname the driver leaves resolution to Docker, so no other change is needed:

[openshell]
version = 2

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

With this, sandboxes reach Ready and the "Run Your First Agent" flow works end to end.

Impact / Why This Matters

The installer targets this platform, but the out-of-box result is a hard failure whose message points at connectivity rather than configuration. runtimes.mdx only says to "set grpc_endpoint when sandboxes cannot reach the gateway on host loopback" and doesn't say what value to use. The obvious guess, the WSL address, doesn't work.

This is a different failure from #3842: on WSL kernel 6.18 the seccomp notification probe passes, and sandbox startup fails later, at gateway connectivity.

Acceptance Criteria

• On WSL 2 + Docker Desktop, a default install plus openshell sandbox create reaches Ready without manual config. The fix could be driver detection (for example, Docker Desktop engine plus a WSL kernel defaulting grpc_endpoint to host.docker.internal), or the Linux installer writing that setting when it detects WSL + Docker Desktop.
• Or, at minimum, the installation and runtime docs describe the working grpc_endpoint for WSL 2 + Docker Desktop.
• The ControlSupervisorStartFailed message for a supervisor that can't reach the gateway mentions grpc_endpoint.

Reproduction Steps

1. Windows 11, WSL 2 in NAT networking mode, Docker Desktop with WSL integration enabled.
2. Install OpenShell 0.1.2 inside the distro and run the gateway as the user service (default bind 127.0.0.1).
3. openshell sandbox create --name demo -- echo hi fails with ControlSupervisorStartFailed.
4. Add the TOML above to ~/.config/openshell/gateway.toml, then systemctl --user restart openshell-gateway.
5. Repeat step 3. The sandbox becomes Ready.

Environment

• OpenShell 0.1.2 (CLI and gateway from the release assets)
• Ubuntu on WSL 2, kernel 6.18.x-microsoft-standard-WSL2, networkingMode=nat
• Docker Desktop, engine 29.4.1
• Compute driver: docker; gateway: local systemd user service with mTLS

[ramanse]

I ran into same issue on macOS

Environment

• macOS 26.6.2, Apple Silicon (M1)
• Docker Desktop 4.76.0, engine 29.5.2
• OpenShell 0.1.2

What happens
openshell status reports Connected and openshell doctor check passes. Then:

openshell sandbox create --name demo --no-auto-providers

fails with:

ControlSupervisorStartFailed: Docker supervisor exited before becoming ready
...
Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server

Workaround
The fix from this issue works on macOS too. I added this to $(brew --prefix)/var/openshell/gateway.toml:

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

and ran brew services restart openshell. After that the sandbox reaches Ready and the first network policy tutorial runs end to end. So this issue is not just limited to to WSL 2. A default install on macOS with Docker Desktop fails the quickstart the same way.

[purp]

📋 triage-agent

Triage Assessment

Classification: validated-bug

Summary

The Docker driver behaves as described. With grpc_endpoint unset, the supervisor container runs with host networking and dials 127.0.0.1:<gateway port>. Under Docker Desktop, "host" is the Docker Desktop VM, not the WSL distro, so this default may not reach a gateway bound to the distro's loopback. The reported workaround (grpc_endpoint = "https://host.docker.internal:17670") is consistent with the code: that name is a default server certificate SAN, and the driver leaves non-localhost hostnames to Docker's resolver. Confidence: medium. The code path is confirmed; the WSL failure was not reproduced here.

Investigation

• Default endpoint: crates/openshell-driver-docker/src/lib.rs:885-890 and :6512-6515 ({scheme}://127.0.0.1:{port}).
• Supervisor host networking: lib.rs:4979-4986. Host aliases are added only for IPv4 addresses and localhost; other hostnames resolve through Docker (lib.rs:5023-5034).
• host.docker.internal SAN: crates/openshell-bootstrap/src/pki.rs:32-41.
• The driver already detects WSL2 from docker info (lib.rs:5582-5595), but only uses it for the GPU fallback (lib.rs:877), not for endpoint selection.
• Docs: docs/how-it-works/sandboxes/runtimes.mdx:97 says to set grpc_endpoint when sandboxes cannot reach host loopback, but gives no value or WSL 2 example. The support matrix lists WSL 2 + Docker Desktop as Experimental.
• Error text: Docker supervisor exited before becoming ready (lib.rs:5380) does not mention grpc_endpoint.
• Distinct from WSL2 (kernel 6.6.87, Docker Engine): sandbox create fails with "seccomp notification probe: notification launcher disappeared" #3842 (seccomp probe failure earlier in startup). No duplicate found. fix(docker): reach a WSL 2 gateway through Docker Desktop's host alias #3924 from the reporter proposes a fix; it has not been reviewed as part of triage.

Open question for the reporter: runtimes.mdx states that Docker Desktop must have host networking enabled (Settings > Resources > Network). Was it enabled in your Docker Desktop when the default configuration failed? This determines whether the loopback default fails even with the documented prerequisite met, or only without it. The docs and error-message gaps apply either way.

Impact Signals

• Affected users/scope: Users on Windows with WSL 2 + Docker Desktop and the Docker driver (an Experimental platform in the support matrix). Every sandbox create fails in the reported setup.
• Regression: No evidence of a regression. Supervisor host networking dates to v0.0.100; reported on v0.1.2 (latest), and the code is unchanged on main.
• Workaround: Available: set [openshell.drivers.docker] grpc_endpoint = "https://host.docker.internal:<port>" and restart the gateway. It is not documented, and the failure message does not point to it.
• Evidence quality: Medium. Clear reproduction steps and environment, and code confirms the default behavior. Not reproduced on WSL here, and the Docker Desktop host-networking setting is unconfirmed.

Human Decision Required

Decide whether OpenShell should address this issue. If yes, apply
state:accepted, associate it with a roadmap item, or do both, and decide
whether the work remains human-owned. Either action records acceptance;
roadmap placement additionally records sequencing.
To queue investigation or planning for an unattended agent, also apply
agent:plan-requested. You can instead directly ask an agent to use
create-spike or build-from-issue on this issue; the agent will warn about
missing expected workflow labels and continue without changing them. If no,
close it as not planned and record the rationale.

[tech4242]

Data point for the open question, on macOS: Docker Desktop 4.93.0 (engine 29.8.1), macOS 26.4.1 on Apple Silicon, OpenShell 0.1.2 standalone gateway bound to 127.0.0.1 with the Docker driver and the default grpc_endpoint.

With host networking off, openshell sandbox create fails with Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server. After enabling host networking (Settings > Resources > Network) and changing nothing else, the same sandbox starts and runs. openshell doctor check reported all checks passed in both cases.

So on macOS the loopback default works once the documented prerequisite is met.

[arjunkchr]

macOS Homebrew repro (0.1.2, Docker Desktop, host networking off)

Confirmed the same failure and workaround on native macOS (not WSL).

Environment

• macOS Darwin 25.6.0, Apple Silicon (arm64)
• OpenShell 0.1.2 via Homebrew (install.sh / brew install nvidia/openshell/openshell)
• Docker Desktop 29.7.2 (engine desktop-linux)
• Gateway: local Homebrew service, mTLS, bound to 127.0.0.1:17670
• Compute driver: docker (auto-detected)
• Docker Desktop host networking: off (default)

Steps

1. openshell status → Connected
2. openshell doctor check → All checks passed
3. openshell sandbox create --name demo --detach

Result (default config)

Sandbox stuck in Error / ControlSupervisorStartFailed:

Docker supervisor exited before becoming ready; log tail:
openshell: log push connect failed: failed to connect to OpenShell server
...
Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server

Supervisor container used network_mode=host with OPENSHELL_ENDPOINT=https://127.0.0.1:17670.
Under Docker Desktop on macOS, host networking is the Docker VM namespace, not the Mac host where the Homebrew gateway listens.

Workaround (works end-to-end)

Add to $(brew --prefix)/var/openshell/gateway.toml:

[openshell.gateway]
compute_driver = "docker"

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

Then:

brew services restart openshell
openshell sandbox delete demo
openshell sandbox create --name demo --detach

Sandbox reaches Ready; openshell sandbox exec -n demo -- uname -a succeeds.

Ask

Please extend #3924 (or equivalent) to cover macOS Homebrew + Docker Desktop, not only WSL 2. Alternatively, ship this grpc_endpoint default in the Homebrew formula's post_install gateway.toml so the quickstart works without manual config.

Related: openshell doctor check passes even when sandboxes cannot reach the gateway (#4133).