[Feature]: detect WSL Containers (wslc) as a Docker environment on Windows

Module

Core

Proposal

Microsoft ships a container runtime with WSL 2.9+ — WSL Containers, driven by the wslc CLI. It runs dockerd inside a lightweight VM, and unlike Docker Desktop or Podman it publishes no Windows named pipe and no TCP port. The only host-visible channel to the daemon is a stdio bridge:

wslc system session run docker system dial-stdio

Because none of the existing strategies can find an endpoint, Testcontainers on such a machine fails at startup with Could not find a valid Docker environment, even though a working daemon is present and wslc can talk to it. The only workaround today is to install Docker Desktop or Podman alongside, which defeats the point of having a runtime already in the OS.

I would like Testcontainers to detect this environment automatically, the same way it already detects a Docker Desktop named pipe.

Environment

• Windows 11, WSL 2.9.4
• wslc from the WSL container runtime
• Testcontainers 2.0.x

Solution

A WslcSocketClientProviderStrategy in core, registered through the existing DockerClientProviderStrategy SPI, that resolves to wslc://localhost when:

• the OS is Windows, and
• the wslc CLI is actually present (probed with wslc version, a metadata call that does not start the container VM).

Priority below NpipeSocketClientProviderStrategy, so an existing Docker Desktop or Podman pipe always wins and nothing changes for current users. wslc is only ever a fallback.

Dependency on docker-java

wslc:// is not a transport docker-java currently understands, so this cannot work on a released docker-java. That side is tracked in docker-java#2658, which proposes a wslc:// transport (a Socket whose streams are the dial-stdio child process, mirroring the existing NamedPipeSocket), plus the lifecycle handling wslc needs for host port relays and Windows-path bind mounts.

So the ordering is: docker-java gains the transport, cf https://github.com/docker-java/docker-java/pull/2659 and releases a version, then Testcontainers picks it up and adds the strategy. I have the Testcontainers side working locally against a locally-built docker-java and I will raise it as a draft PR.

Benefit

WSLC support out of the box, no more need for docker or podman on Windows

Alternatives

** Keep using podman or docker

Set DOCKER_HOST=wslc://localhost manually. Works once docker-java understands the scheme, and is a reasonable escape hatch, but it means every developer and CI job on such a machine has to know to do it — which is exactly the discovery problem the strategies exist to solve.

A ~/.testcontainers.properties strategy override. Same objection, plus it has to name a class that does not exist upstream.

Reach the daemon over TCP inside the VM. Requires reconfiguring dockerd inside the WSL container VM to listen on a port and exposing it to the host — insecure, non-default, and undoes the isolation the runtime is providing.

Would you like to help contributing this feature?

Yes

Beginnen Sie mit der bestehenden DockerClientProviderStrategy-SPI und NpipeSocketClientProviderStrategy und prüfen Sie anschließend docker-java#2658 sowie Pull Request #2659 auf den erforderlichen wslc://-Transport. Überprüfen Sie die wslc-Versionsprüfung ohne Start und die Fallback-Priorität unter Windows. Als abgeschlossen gilt die Aufgabe, wenn die Strategie wslc://localhost erkennt, sofern keine bestehende Pipe-Strategie greift, und mit einem veröffentlichten docker-java-Transport funktioniert.