microsoft / microsoft/WSL

[Feature Request] Support DOCKER_HOST via Docker Engine API-compatible endpoint in WSLC

Open
#40,976 6 comments 19 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature wslc
Dominant language
C++
Stars
33.7k
Forks
1.8k
Avg merge
3d 17h
Merged PRs (30d)
116

Description

Description

WSLC (WSL Container) currently operates only through its own CLI (wslc.exe) and API (Microsoft.WSL.Containers NuGet package). There is no way for tools that expect the Docker Engine API (via the DOCKER_HOST environment variable) to connect to WSLC. This prevents using WSLC as a drop-in replacement for Docker Desktop.

Many tools in the container ecosystem rely on DOCKER_HOST / Docker Engine API, including:

  • nektos/act — run GitHub Actions locally
  • docker CLI — the standard Docker client
  • Docker Compose — multi-container orchestration
  • Testcontainers — integration testing with containers
  • Podman (with podman.socket) — already exposes a Docker-compatible API
  • buildx / buildkit — advanced image building

Current Workaround

Users must keep Docker Desktop installed alongside WSLC, defeating the purpose of a built-in container runtime. For example, running ct locally requires Docker Desktop's socket (//./pipe/docker_engine). There is no way to point DOCKER_HOST at a WSLC endpoint.

Proposed Solution

Add a Docker Engine API-compatible endpoint to WSLC, configurable in settings.yaml. Similar to how Podman exposes podman.socket:

`yaml

settings.yaml

session:
cpuCount: default
memorySize: default

New: Docker-compatible API endpoint

docker:
socket: true # Enable Docker-compatible socket
socketPath: "//./pipe/wslc_docker" # Windows named pipe (default)

or

tcp: "127.0.0.1:2375" # TCP endpoint (optional)
`

Then users could set:

`powershell
= "npipe:////./pipe/wslc_docker"

or

= "tcp://127.0.0.1:2375"
`

And tools like ct, docker, compose would work transparently.

Environment

  • WSLC version: Latest (Preview)
  • Windows version: Windows 11
  • Use case: Running
    ektos/act for local CI testing, replacing Docker Desktop

Additional Context

Both Podman and Docker Desktop already support this pattern. Adding Docker Engine API compatibility to WSLC would make it a true Docker Desktop alternative and significantly broaden its adoption in the development ecosystem.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing WSLC's existing wslc.exe and Microsoft.WSL.Containers API, along with the proposed settings.yaml configuration. Done means WSLC exposes a Docker Engine API-compatible endpoint that tools can reach through DOCKER_HOST using the documented named-pipe or TCP configuration.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, docker
Domain
api, operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.