title	description	ms.date	ms.topic
NanoWhale	Windows named-pipe bridge for Docker clients that need to reach the Docker socket inside WSL	2026-04-06	overview

Overview

NanoWhale exposes a Windows named pipe and forwards each client connection into WSL with socat. That lets Windows-native Docker clients talk to a Docker daemon that only exposes /run/docker.sock inside WSL.

The default pipe path is \\.\pipe\dockerWSL, so you can point Docker at it with PowerShell:

$env:DOCKER_HOST = "npipe:////./pipe/dockerWSL"
docker info

Prerequisites

• Windows host with WSL installed
• A WSL distribution that exposes the Docker socket at /run/docker.sock
• socat installed inside that WSL distribution
• Go 1.26 or later if you want to build from source

Install socat inside WSL if it is not already available:

sudo apt-get update
sudo apt-get install -y socat

Quick Docker Setup

Use this setup if you want a Windows Docker CLI that talks to a Docker Engine running inside WSL.

1. Install WSL on Windows:

wsl --install

2. Install Docker Engine inside your Ubuntu WSL distribution by following the official guide:

https://docs.docker.com/engine/install/ubuntu/

3. Install the Windows Docker CLI and plugins:

Component	Download	Install location
Docker CLI	docker-29.3.1.zip	Extract docker.exe into a folder on your PATH
Buildx plugin	docker-buildx.exe	%USERPROFILE%\.docker\cli-plugins\docker-buildx.exe
Compose plugin	docker-compose.exe	%USERPROFILE%\.docker\cli-plugins\docker-compose.exe

Create the Docker CLI plugin directory if it does not already exist:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.docker\cli-plugins"

4. Start the Docker daemon inside WSL, then point the Windows CLI at NanoWhale:

$env:DOCKER_HOST = "npipe:////./pipe/dockerWSL"
docker info

Build And Run

Build the relay:

go build -mod=readonly -ldflags="-s -w" -trimpath .

Build a native Windows tray executable without a console window:

go build -mod=readonly -ldflags="-H=windowsgui -s -w" -trimpath .

Run it from Explorer, Start Menu, or PowerShell:

.\NanoWhale.exe

Show the built-in help:

.\NanoWhale.exe --help

The GUI build shows help and startup errors in a Windows message box.

The process validates that WSL can find socat and that the Docker socket exists before it starts listening.

Configuration

NanoWhale is configured with command-line flags.

Flag	Default	Purpose
--pipe	\\.\pipe\dockerWSL	Windows named pipe path exposed to Docker clients
--socket	/run/docker.sock	Docker socket path inside WSL
--wsl	wsl.exe	WSL launcher executable
--distro	empty	Optional WSL distribution name passed to wsl.exe -d
--startup-timeout	10s	Timeout for the startup backend validation
--shutdown-timeout	10s	Time allowed for active sessions to drain during shutdown
--validate-backend	true	Enables the startup probe that checks socat and the Docker socket

Example configuration for a specific distribution:

.\NanoWhale.exe --distro Ubuntu-24.04

Security

NanoWhale uses a fixed pipe security descriptor: D:P(A;;GA;;;OW)(A;;GA;;;SY). That grants access to the owner of the process and SYSTEM.

Important

Anyone who can open the pipe can issue Docker API calls against the daemon in WSL.

Operational Notes

• Each client connection launches an isolated wsl.exe plus socat bridge
• NanoWhale runs in the Windows notification area by default and stops from the Close menu
• Startup failures include stderr from WSL when available, which makes missing socat, a wrong distribution, or a missing socket easier to diagnose

Validation

Use the standard Go checks before packaging a release:

go test ./...
go vet ./...
go build ./...