How-To: Seamless development in WSL2 with git, SSH and podman desktop

Weather you want a more uniform development environment across your team to avoid compatibility issues between different operating systems, want to work closer to your target environment, or need to run a linux exclusive tool like Claude Code, an AI coding assistant.
There are many reasons to move to a more unix-like workflow when you are developing on Windows.

Natively on Windows your Git/SSH setup works fine and your keys are automatically added and removed to and from your ssh-agent by your password manager.
For docker related tasks your podman desktop installation serves you well.
However, they are not immediately available within WSL on your fresh linux distro. The SSH-Agent is not running or not persistent over multiple sessions and you have to re-enter your password because your password manager does not see your WSL environment. Installing docker in WSL requires re-pulling images, resulting in duplicated images and containers between Windows and WSL.
This situation is undesirable.

Use your Windows SSH-agent in WSL

Since everything is already set up in Windows we'll use that.

WSL adds .exe files from the Windows PATH to the WSL PATH. The exe versions automatically use the Windows services and configs.

1$ ssh -T git@gitlab.com
2
3> git@gitlab.com: Permission denied (publickey).
4
5$ ssh.exe -T git@gitlab.com
6
7> Welcome to Gitlab, @username!

Easy, lets just create an alias for ssh.

1alias ssh ssh.exe
2alias ssh-add ssh-add.exe
3alias ssh-keygen ssh-keygen.exe

ℹ | INFO
Binding the ssh-agent from Windows into WSL would be possible but requires additional software that has to be built manually from a github repo. » npiperelay

Configuring Git in WSL for using Windows SSH

Still, this is not enough for git. We need to tell git explicitly which program to use for ssh/gpg things. Just aliasing the command in the shell does not work.
Edit your global .gitconfig in WSL accordingly:

cloning and synchronization

1[core]
2       sshcommand = ssh.exe
3[http]
4       sslBackend = gnutls

commit signing

1[user]
2        signingkey = <content of your public key>
3[gpg]
4        format = ssh
5[gpg "ssh"]
6        program = ssh-keygen.exe
7        allowedSignersFile = /mnt/c/users/<your account name>/.ssh/allowed_signers
8[commit]
9        gpgsign = true

🌐| See git ssh and gpg settings documentation.

Now you should be able to authenticate and sign your commits using your ssh-agent running in the Windows host system.

🗒️| NOTE
Why not just use git.exe? - The file system I/O between Windows and WSL is very slow. Therefore it is generally not recommended to mix Windows and WSL file systems in your projects.
Doing so would cause massive slow downs in git scanning your project.

Install and connect the docker-/podman-cli to podman desktop

in Ubuntu/WSL

So can we just do the same with docker/podman? - Probably not.
Using basic commands works fine that way but when using file mounts we'll have a mismatch between WSL and Windows file paths.
Also some dev tools require the docker socket or expect an actual executable.

First we'll look into how to access podman from another WSL distribution.
Podman desktop provides sockets to communicate with the engine at /mnt/wsl/podman-sockets/podman-machine-default/.
We can use the same method described in the podman desktop documentation to connect an actual docker-cli to podman.

❗| ATTENTION
As of version 29 Docker removed support for the API v1.41 which is used by podman for docker compatibility. The minimum API version supported by Docker now is v1.44,
so you might need to install an older docker-cli.

Simply create a new context for the podman socket and tell docker to use it:

1docker context create podman-root --docker "host=unix:///mnt/wsl/podman-sockets/podman-machine-default/podman-root.sock"
2 docker context use podman-root

Alternatively you can also use the DOCKER_HOST variable.

in Windows

On Windows we can install the docker client binaries.
Though, as the docker CLI on windows doesn't come with the compose and buildx plugins, we need to install those too.
They are also available as winget packages.

If you opted for the winget packages, or didn't install the compose and buildx binaries into the docker plugin folder, you can add a symlink that points to the binaries.

1winget add Docker.DockerCLI
2winget add Docker.DockerCompose
3winget add Docker.Buildx
4
5sudo Powershell.exe ni -Path ~/.docker/cli-plugins/docker-compose.exe -ItemType SymbolicLink -Value "$($Env:LocalAppData)\Microsoft\WinGet\Packages\Docker.DockerCompose_Microsoft.Winget.Source_8wekyb3d8bbwe\docker-compose.exe" -Force
6sudo Powershell.exe ni -Path ~/.docker/cli-plugins/docker-buildx.exe -ItemType SymbolicLink -Value "$($Env:LocalAppData)\Microsoft\WinGet\Packages\Docker.Buildx_Microsoft.Winget.Source_8wekyb3d8bbwe\docker-buildx.exe" -Force

ℹ | INFORMATION
sudo for Windows is an optional developer feature that elevates a process with administrative rights.
But it can not run commands directly.

With docker compatibility enabled in podman desktop, this should work without further configuration of the context.

---

ℹ | INFORMATION
When trying to run devcontainers with anything other than docker, you'll inevitably run into issues - Even using docker does not guarantee an error free experience.

In this discussion you can find a collection of workarounds for common issues with podman in WSL and devcontainers.
Additionally you might have to change the engine runtime from runc to crun when you are getting the error "bind mounts cannot have any filesystem-specific options applied" or invalid additional build context format: {"dev_containers_feature_content_source":{"IsURL":false,"IsImage":false,"Value":"/tmp/devcontainercli » ~/.config/containers/containers.conf:

1[engine]
2runtime = "/user/bin/crun"