[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

Inizia con la SPI esistente DockerClientProviderStrategy e NpipeSocketClientProviderStrategy, quindi esamina docker-java#2658 e la pull request #2659 per il trasporto wslc:// richiesto. Verifica il controllo della versione di wslc senza avvio e la priorità del fallback su Windows. Il lavoro è completato quando la strategia rileva wslc://localhost se non si applica alcuna strategia pipe esistente e funziona con un trasporto docker-java rilasciato.