Docker provider via WSL

This tutorial runs a Docker engine inside WSL2 and connects Devsy, running on Windows, to it over SSH. Docker and the project files stay in the WSL filesystem for speed, while Devsy and the editor run on Windows.

Install Docker in WSLCopy Anchor Link

Enable WSL2Copy Anchor Link

In PowerShell as Administrator, skip this step if WSL2 is already installed:

wsl --install

This enables the required features and installs a default Linux distribution. Without wsl --install, enable both the Windows Subsystem for Linux and the Virtual Machine Platform features by hand, restart, and run wsl --set-default-version 2. Without the Virtual Machine Platform, WSL falls back to WSL1.

To install a specific distribution, run wsl --install Ubuntu-24.04 and set a username and password. Open its shell with wsl.

[boot]
systemd=true

Install Docker EngineCopy Anchor Link

Follow the official Docker Engine installation for Ubuntu inside WSL. Then add your user to the docker group and start the services:

sudo usermod -aG docker $USER
sudo systemctl enable --now docker.service containerd.service

Behind a corporate proxy, also configure the Docker daemon proxy.

Install an SSH serverCopy Anchor Link

The Windows Docker client reaches the daemon over SSH, not an open TCP port:

sudo apt-get update
sudo apt-get install -y openssh-server
sudo systemctl enable --now ssh.service

WSL2 forwards localhost to Windows, so the server is reachable there. To avoid password prompts, run ssh-keygen on Windows and append the public key to ~/.ssh/authorized_keys in WSL.

Connect Windows to the daemonCopy Anchor Link

Download the Docker CLI from the Docker static binaries for Windows, extract it, and add its folder to PATH. Then create a context that uses SSH. Replace <wsl-username> with your WSL username:

docker context create lin --docker "host=ssh://<wsl-username>@localhost"
docker context use lin
docker run hello-world

The first connection asks you to accept the SSH host key.

Connect DevsyCopy Anchor Link

Add the Docker provider and point it at the WSL daemon:

devsy provider add docker -o DOCKER_HOST=ssh://<wsl-username>@localhost -o DOCKER_PATH=docker

If the provider already exists, use devsy provider set docker -o ... with the same options. Check the result with devsy provider get docker.

DOCKER_HOST accepts anything the Docker CLI accepts.

Connect your editorCopy Anchor Link

Create the workspace. Devsy adds an SSH config entry named <workspace-name>.devsy:

devsy up

In VS Code or VSCodium with the Open Remote - SSH extension, choose Open Folder in Remote... and select that host. Devsy tunnels the session into the dev container, so no jump host setup is needed.

The tunnel reuses your local SSH keys and agent. If the editor log shows write EPIPE, run devsy up with DEVSY_DEBUG=true. The real cause, such as the WSL SSH server not running or an untrusted host key, is otherwise hidden behind that generic error.

Next stepsCopy Anchor Link

See Create a Workspace.