Docker provider via WSL
This tutorial runs Docker Engine in WSL2 and connects Devsy on Windows to it over SSH. Devsy and the editor run on Windows. Keep project files on a Windows drive so Devsy can translate their mount paths into WSL paths.
Install Docker in WSL
Enable WSL2
If WSL2 is not installed, run this in PowerShell as Administrator:
wsl --installwsl --install enables the required features and installs a default Linux distribution. Without it, enable the Windows Subsystem for Linux and Virtual Machine Platform features by hand, restart, and run wsl --set-default-version 2. Without Virtual Machine Platform, WSL uses WSL1.
To install a specific distribution, run wsl --install Ubuntu-24.04 and set a username and password. Open its shell with wsl.
The steps below use systemctl, which needs systemd. If systemd is missing, add this to /etc/wsl.conf, run wsl --shutdown from PowerShell, and start wsl again:
[boot]
systemd=trueInstall Docker Engine
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.serviceBehind a corporate proxy, also configure the Docker daemon proxy.
Install an SSH server
The Windows Docker client reaches the daemon over SSH, so no TCP port needs to be open:
sudo apt-get update
sudo apt-get install -y openssh-server
sudo systemctl enable --now ssh.serviceWSL2 forwards localhost to Windows. To skip password prompts, run ssh-keygen on Windows and append the public key to ~/.ssh/authorized_keys in WSL.
Connect Windows to the daemon
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-worldThe first connection asks you to accept the SSH host key.
Connect Devsy
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=dockerIf 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.
How Devsy mounts project files
When DOCKER_HOST is not a local socket, Devsy converts Windows drive paths in mounts to their WSL form. A project at C:\Users\me\repo is mounted as /mnt/c/Users/me/repo. Keep project files on a Windows drive. Paths under \\wsl.localhost\... are not supported for mounts.
Connect your editor
Create the workspace. Devsy adds an SSH config entry named <workspace-name>.devsy:
devsy workspace upIn 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 you need no jump host.
The tunnel uses your local SSH keys and agent. If the editor log shows write EPIPE, run devsy workspace up with DEVSY_DEBUG=true to see the cause, such as a stopped WSL SSH server or an untrusted host key.
Next steps
See Create a Workspace.
Experimental WSLg display discovery
Devsy on Windows can read display values from a WSL2 distribution and non-root user that you select. You opt in. It needs a local Docker provider (the built-in docker provider or a named copy) with Docker Engine in that distribution, as configured above. It does not support Docker Desktop, Podman, remote providers, or Devsy running inside WSL. The Docker endpoint must reach the same distribution.
Check that a GUI application runs in your distribution and that these PowerShell commands return its display values. Replace the distribution and username:
wsl.exe --distribution Ubuntu-24.04 --user alice --exec /usr/bin/printenv DISPLAY
wsl.exe --distribution Ubuntu-24.04 --user alice --exec /usr/bin/printenv WAYLAND_DISPLAY
wsl.exe --distribution Ubuntu-24.04 --user alice --exec /usr/bin/printenv XDG_RUNTIME_DIRDevsy runs the same noninteractive probe with a 30-second limit. It does not start a login shell or read shell profiles. If these commands cannot read the values your GUI application uses, discovery cannot support your setup.
Enable discovery in the Devsy context your workspace uses:
devsy context set -o WSLG_ENABLED=true -o WSLG_DISTRO=Ubuntu-24.04 -o WSLG_USER=aliceDevsy exposes these values:
| WSL value | Devsy substitution and Compose interpolation key |
|---|---|
DISPLAY | DEVSY_WSLG_DISPLAY |
WAYLAND_DISPLAY | DEVSY_WSLG_WAYLAND_DISPLAY |
XDG_RUNTIME_DIR | DEVSY_WSLG_XDG_RUNTIME_DIR |
Missing values stay absent. Empty values stay empty. Discovery sets no container environment and adds no mounts, so map the values you need in your project. While discovery is enabled, Compose does not interpolate $ in containerEnv values. Devsy does not import audio, GPU, session bus, SSH sockets, or WAYLAND_SOCKET file descriptors.
Devsy reserves these names while discovery is enabled. Remove assignments to them from your Windows environment, --init-env, provider Docker environment, and Compose interpolation .env files. Devsy rejects empty assignments and differently cased Windows names. Plain DISPLAY stays under your control. Service env_file entries set container environment and are separate from interpolation files. COMPOSE_ENV_FILES does not work while discovery is enabled. Use the project .env files that Devsy passes.
X11 configuration mechanics
These examples need an image with an X11 client, a running WSLg server, and a /tmp/.X11-unix/X0 socket that the Docker daemon can see. Test that a window appears on your machine. See Microsoft's WSLg container guidance for the socket requirements.
For an image or Dockerfile devcontainer, map the display and bind the socket with Docker runArgs:
{
"image": "your-image-with-an-x11-client",
"containerEnv": {
"DISPLAY": "${localEnv:DEVSY_WSLG_DISPLAY}"
},
"runArgs": [
"--mount",
"type=bind,source=/tmp/.X11-unix,target=/tmp/.X11-unix,readonly"
]
}Use runArgs because the mounts property checks bind sources on the Windows client, and this socket exists only on the daemon. A missing source fails instead of creating a directory.
For Compose, the values are available when Devsy loads the Compose files and when Compose processes them:
services:
dev:
image: your-image-with-an-x11-client
command: sleep infinity
environment:
DISPLAY: "${DEVSY_WSLG_DISPLAY:?Enable WSLg discovery for this context}"
volumes:
- type: bind
source: /tmp/.X11-unix
target: /tmp/.X11-unix
read_only: true
bind:
create_host_path: falseA read-only mount of a Unix socket still lets the container talk to the server. Give GUI access only to projects you trust. Devsy does not change X11 authorization, socket permissions, user IDs, or host networking. remoteEnv applies only to later remote sessions. It does not affect Compose interpolation or the container entrypoint.
Wayland and lifecycle
Map Wayland values the same way. XDG_RUNTIME_DIR is a host path with ownership and permission requirements. Do not copy it into the container or mount the host /run/user directory. Map only the Wayland socket into a container runtime directory that the intended user owns, or use an absolute socket path with a client that supports it. This page has no tested Wayland example.
Each up, recreate, and build reads the display values again. Devsy reuses a running container only when the recorded distribution, user, and values match. Run devsy workspace up --recreate for a stopped WSLg container, changed values, newly enabled discovery, or opting out. After a WSL restart, run it even if the values match, because the sockets may have changed.
Stop and delete do not probe WSL. Containers carry a label with the distribution, user, and display values. Compose containers also record the Compose paths that cleanup needs. Anyone who can inspect the Docker daemon can read these labels. They hold connection metadata, not credentials. Workspace logs record command output, so a hook or build step that prints DEVSY_WSLG_* values stores them there. Cleanup needs a reachable Docker daemon and, for Compose, the original project files.
Disable discovery with:
devsy context set -o WSLG_ENABLED=falseRecreate existing WSLg workspaces after you change this setting. With discovery disabled, Devsy resolves the environment as usual and does not call WSL.