Skip to content

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

Open
#3924
Open
bug(docker): sandboxes never become Ready on WSL 2 + Docker Desktop (supervisor dials 127.0.0.1)#3880
#3924
Labels
area:computestate:acceptedA maintainer decided OpenShell should pursue this issuetopic:compatibilityCompatibility-related worktopic:networking

Description

@fede-kamel
fede-kamel
opened on Sep 29, 2026

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

Activity

  1. github-actions
    added
    state:triage-neededOpened without agent diagnostics and needs triage
    on Sep 29, 2026
  2. fede-kamel
    added a commit that references this issue on Sep 30, 2026

    fix(docker): match Docker Desktop's variant operating system names

    02bb080

  3. ramanse commented on Oct 1, 2026

    @ramanse
    ramanse
    on Oct 1, 2026

    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.

  4. purp commented on Oct 1, 2026

    @purp
    purp
    on Oct 1, 2026
    Collaborator

    📋 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.

  5. purp
    added
    state:acceptedA maintainer decided OpenShell should pursue this issue
    area:compute
    topic:networking
    topic:compatibilityCompatibility-related work
    and removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Oct 1, 2026

  6. tech4242 commented on Oct 2, 2026

    @tech4242
    tech4242
    on Oct 2, 2026

    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.

  7. arjunkchr commented on Oct 3, 2026

    @arjunkchr
    arjunkchr
    on Oct 3, 2026

    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).

  8. SoniaMehta14
    added a commit that references this issue on Oct 9, 2026

    OpenShell Phase 1: friction log for install and first run on macOS

    59a7366

  9. SoniaMehta14 commented on Oct 9, 2026

    @SoniaMehta14
    SoniaMehta14
    on Oct 9, 2026

    Adding a macOS data point, and a side effect of the workaround above that took a while to trace.

    Environment

    • macOS 26.6.2, Apple Silicon
    • Docker Desktop 4.88.1 (engine 29.8.2)
    • OpenShell 0.1.2, installed with install.sh and OPENSHELL_VERSION=v0.1.2, gateway running as the Homebrew service on 127.0.0.1:17670

    1. A fresh install reproduces this issue. The first sandbox create fails after about 13 seconds with ControlSupervisorStartFailed: Docker supervisor exited before becoming ready and Startup configuration fetch failed after 5 attempts: failed to connect to OpenShell server, even though openshell status reports Connected.

    2. The workaround makes sandboxes start, but they can no longer reach the host. @arjunkchr, one caution on making this the default: with

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

    sandboxes start in under a second. But inside the sandbox, host.openshell.internal and host.docker.internal both fail to resolve ("No address associated with hostname"), even with a policy that allows them. The sandbox log shows:

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

    3. Cause, from reading the v0.1.2 source. The supervisor takes its trusted host gateway from a host.openshell.internal line in its own /etc/hosts (detect_trusted_host_gateway in proxy.rs). The Docker driver only adds that line when grpc_endpoint is an IPv4 literal or localhost (docker_supervisor_host_address in the Docker driver lib.rs, around lines 4999 to 5009). With a hostname endpoint it returns None, the supervisor container gets ExtraHosts=[] (confirmed with docker inspect), and every host alias is refused. Pointing grpc_endpoint at the VM host address (192.168.65.254) would add the line, but the generated server certificate has no IP SAN for that address (I checked the SAN list with openssl x509), so I expect TLS verification to fail. I did not test this: I never created a sandbox with that endpoint.

    So on Docker Desktop for Mac the choice today is: sandboxes do not start (default), or sandboxes start but cannot reach any service on the host (workaround). The supervisor middleware example in the docs (http://host.openshell.internal:50051) needs exactly that host access.

    4. What works. Enabling Docker Desktop host networking (Settings, Resources, Network) and keeping the default gateway config, as reported above. Sandboxes start in under a second and reach host.openshell.internal, and default deny still holds: with a policy allowing one host port, probes to other host ports, the gateway port, public hosts, Docker's host IP and loopback were all refused.

    Suggestions

    • Have the Docker driver add host.openshell.internal when grpc_endpoint is host.docker.internal (resolve it when the sandbox is created), or allow the host gateway address to be set in the driver config.
    • The sandbox runtimes page already says Docker Desktop must have host networking enabled. Surfacing that in the support matrix and the installation page would catch it before the first sandbox create, and troubleshooting entries for ControlSupervisorStartFailed and the undocumented policy_dns_trusted_gateway_unavailable reason code would help anyone who misses it.

    The full timestamped log, with commands, outputs and source links, is public here (entries 13 to 20 and 27): https://github.com/SoniaMehta14/paved-gate/blob/main/docs/openshell/FRICTION_LOG.md

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:computestate:acceptedA maintainer decided OpenShell should pursue this issuetopic:compatibilityCompatibility-related worktopic:networking

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions