Please Add/Release Windows Version

[rafi021]

Please Add Windows Version

[geodro]

Hey, thanks for the interest in a Windows version. The honest blocker is I don't have a Windows device to develop and test on, so I can't realistically build or support a native Windows port myself right now. On the technical side it would also be a meaningful amount of work since the architecture leans on rootless Podman quadlets and systemd user services on Linux, and on macOS we just shipped a launchd plus host workers port, so a third platform would mean another fully separate runtime path. The realistic path on Windows today is WSL2 with systemd enabled, which gives you a real Linux user session where the existing Linux build runs unchanged, install script and quadlets and all. I'll leave the issue open as a tracker, if interest grows or someone with a Windows machine wants to help drive a port that changes the equation.

[DotaninDev]

use laragon

[Jgamboaa]

hey @geodro , I have a Windows computer I can use for testing. How can I help?

[geodro]

Hey @Jgamboaa, really appreciate the offer. A native Windows port still isn't on the table right now, no Windows machine here, plus it would mean a third fully separate runtime path next to the Linux quadlets and macOS launchd. There is something concrete you could help with that would actually move the needle for Windows users though.

Below is a draft WSL2 install guide we'd like to land as docs/getting-started/wsl2.md. It covers the lerd-specific gotchas we know about from the code, but it hasn't been walked through on a real Windows + WSL2 machine yet, and that's where we need help. If you have time to follow it step by step and report back anything that's wrong, missing, or worded confusingly, I'll incorporate the feedback and ship the page upstream.

---

Installing lerd on WSL2 (Ubuntu / Debian)

lerd runs on WSL2, but some assumptions it makes on native Linux (systemd active, NetworkManager or systemd-resolved managing DNS, browser on the same host) don't hold on WSL by default. This page is the minimum configuration to get everything working.

Supported distros: Ubuntu 22.04+ or Debian 12+ running on WSL >= 0.67.6 (which brought official systemd support). Older versions need workarounds like genie or subsystemctl that aren't tested here.

1. Enable systemd inside WSL2

lerd's whole architecture (Quadlet, watcher, UI, FPM) runs as systemd user units. Without systemd, nothing starts.

Inside the WSL distro, create or edit /etc/wsl.conf:

[boot]
systemd=true

[user]
default=your-user

Then from PowerShell on Windows:

wsl --shutdown

Reopen the WSL terminal and confirm:

ps -p 1 -o comm=
# expected: systemd

systemctl --user status
# should respond without error

2. Configure networkingMode=mirrored (recommended)

Without this, http://yoursite.localhost only responds inside WSL, Chrome on the Windows side won't find it. With mirrored networking, the WSL2 network interface mirrors the Windows one and localhost works from both sides.

On Windows, create or edit %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

Then wsl --shutdown again.

Requires WSL >= 2.0.0 and Windows 11 22H2+. Without mirrored networking you can still hit the WSL VM IP from Windows (ip addr show eth0) or use a browser installed inside WSL via wslview / xdg-open.

3. Install the base packages

sudo apt update
sudo apt install -y \
  podman uidmap fuse-overlayfs slirp4netns \
  curl git unzip libnss3-tools

podman plus uidmap and slirp4netns give you rootless containers. fuse-overlayfs is the fallback when the WSL kernel's overlayfs misbehaves. libnss3-tools provides the certutil that mkcert needs.

Do not install docker.io or docker-ce alongside lerd on WSL2, lerd is built exclusively for rootless Podman with Quadlet.

4. Run the installer in .localhost mode

curl -fsSL https://raw.githubusercontent.com/geodro/lerd/main/install.sh | bash

When it asks *"Let lerd manage DNS for local sites (No: use .localhost, no dnsmasq, no HTTPS)?" answer No. The installer will switch the TLD to localhost, which resolves to loopback automatically (RFC 6761) without needing systemd-resolved or NetworkManager dispatcher hooks.

Do not choose the .test mode on WSL2. The DNS setup in internal/dns/setup.go writes a resolved drop-in or NetworkManager dispatcher script, and neither service runs by default on WSL2 Ubuntu / Debian, so it will fail.

The installer will also try to enable linger automatically via sudo loginctl enable-linger $USER so the containers keep running after you close the terminal. If that step is skipped for any reason, run it manually and then wsl --shutdown plus reopen.

5. Keep projects in $HOME, not in /mnt/c/...

This is the single biggest performance lever on WSL2. Bind mounts from /mnt/c/... into containers go through 9P, which is orders of magnitude slower than the WSL2 ext4 filesystem.

# Avoid (composer / npm install will be 10x slower)
cd /mnt/c/Users/you/projects/myapp
lerd link

# Do
mkdir -p ~/projects
cd ~/projects
git clone git@github.com:org/myapp.git
cd myapp
lerd link

If you want to edit from VS Code on Windows, use the Remote-WSL extension and open the folder directly from the WSL side (code . inside WSL launches the Windows VS Code pointed at ext4).

6. HTTPS and mkcert on WSL2

If you run lerd secure, mkcert installs the root CA into the WSL trust store, not the Windows one. The result:

• A browser installed inside WSL (Firefox or Chromium from apt) will trust the cert.
• A browser on Windows (Chrome, Edge, Firefox) will not.

Two options:

• For day to day local dev, use HTTP (http://yoursite.localhost). It covers most of what you need.
• For HTTPS that's trusted by the Windows browser, copy the mkcert root CA out and install it in Windows by hand:

cp "$(mkcert -CAROOT)/rootCA.pem" /mnt/c/Users/$USER/Desktop/lerd-rootCA.crt

Then on Windows, double-click the file and import it into "Trusted Root Certification Authorities".

7. The system tray doesn't work on WSL2

lerd-tray needs a graphical tray host (StatusNotifierItem / AppIndicator), and WSL2 doesn't provide one. Nothing else is affected, you drive everything via the CLI or via the dashboard at http://lerd.localhost.

To silence the unit so it stops complaining in logs:

systemctl --user mask lerd-tray.service

Final checklist

Before lerd link on your first project, validate the setup end to end:

# systemd as PID 1
ps -p 1 -o comm=                                   # systemd

# user session up
systemctl --user is-active default.target          # active

# linger
loginctl show-user $USER --property=Linger         # Linger=yes

# rootless podman
podman info --format '{{.Host.Security.Rootless}}' # true

# overlay driver
podman info --format '{{.Store.GraphDriverName}}'  # overlay

# lerd UI running
systemctl --user is-active lerd-ui                 # active

# .localhost resolution
getent hosts test.localhost                        # ::1 / 127.0.0.1

If all of those come back green, cd ~/projects/myapp && lerd link should behave exactly the same as on native Linux.

Troubleshooting

Symptom	Fix
System has not been booted with systemd as init	Add [boot] systemd=true to /etc/wsl.conf, then wsl --shutdown
Failed to connect to bus from systemctl --user	Linger isn't enabled or you didn't relog after enabling it
http://...localhost doesn't open in Chrome on Windows	networkingMode=mirrored is missing from .wslconfig
Composer or npm install painfully slow	Project is under /mnt/c/..., move it into ~/projects/
podman build fails on overlay	sudo apt install fuse-overlayfs && podman system reset
lerd doctor complains about DNS	You chose the .test mode at install time, reinstall and pick .localhost
cannot allocate memory on large builds	Raise WSL VM memory: [wsl2] memory=8GB in .wslconfig

---

If you can run through that and let us know which steps land cleanly, which need extra context, and which break outright on a real Windows + WSL2 machine, we'll fold the corrections in and ship it as a proper docs page. That's probably the highest leverage way for a Windows user to make lerd nicer on Windows without going down the full native port road.

[stevebrainng]

I installed this and everything works fine for windows wsl 2 Ubuntu. even the .test domain name works perfectly.

Here's how I installed it:

I followed the podman install instruction in: https://gist.github.com/GiovanniGrieco/94ab72099fa35bc307fda0e36b88f1bd

then I installed Lerd following the normal approach.

When it asks *"Let lerd manage DNS for local sites (No: use .localhost, no dnsmasq, no HTTPS)?"
I answered YES, because I previously had valet for linux installed and .test works well with wsl2 infact in removed valet for linux in place of lerd because valet was always having 503 error issue.

I had a port already in use - issue with the previous nginx installed by valet but I stopped the service deleted that nginx and started lerd again lerd stop lerd start and then I followed the approach here to install the Root Certificate.

When installing the Root Cert in the Certificate Import Wizard: In the Certificate Store step, Select Place all certificates in the following store and then choose Trusted Root Cert Authrities

The Certificate installation was a nice hack I really appreciate that. @geodro Thanks for Lerd

[stevebrainng]

Update: While everything works fine as expected I'm getting the following in the Lerd DNS section on the dashboard.

lerd-dns is healthy and answering directly, but the system resolver isn't routing your domains to it, usually because a VPN client rewrote DNS. Sites still resolve, and lerd re-syncs container DNS automatically when the VPN connection changes.

Also these Error logs on all Lerd service logs.
Error: using --follow with the journald --log-driver but without the journald --events-backend (file) is not supported
Error: using --follow with the journald --log-driver but without the journald --events-backend (file) is not supported
Error: using --follow with the journald --log-driver but without the journald --events-backend (file) is not supported

I'm getting this has something to do with the podman installation step in the link I shared https://gist.github.com/GiovanniGrieco/94ab72099fa35bc307fda0e36b88f1bd

Which says: Now, please edit $HOME/.config/containers/containers.conf with a text editor and ensure the following lines are set correctly:

cgroup_manager = "cgroupfs"
events_logger = "file"

after changing the events_logger to "journald" I started seeing the logs on the dashboard and the the Error: using disappered.

[geodro]

Hey @stevebrainng, huge thanks for the writeup and especially for tracking down the events_logger fix, that one would have eaten people's afternoons for ages if you had not posted it. Your YES on the DNS prompt working cleanly was also useful, the earlier draft told people to avoid .test mode on WSL2 and your report is what changed my mind.

I have rolled all of that into a proper docs page now and the PR is at #432. Before I merge it I want at least one more person to walk through the steps end to end on a real Windows plus WSL2 box and confirm everything lands cleanly. If you, or anyone else on this thread (@Jgamboaa, your offer still stands if you have the time), can read through the page and try the install from scratch, that is the green light I need to ship it. Once we have that confirmation it goes into main and the page goes live at geodro.github.io/lerd/getting-started/wsl2.

If you spot anything missing or wrong while you go through it, drop a comment on the PR or here and I will fold the fix in.

[stevebrainng]

I have gone through it again, I installed a fresh wsl Ubuntu 24.04 and went through the installation from scratch using the docs you created at #432. and everything was smooth and clean from the install.

only one thing to note though: When the wsl terminal is launched I get this log on the terminal

wsl: Unknown key 'wsl2.pageReporting' in C:\Users\MYPCUSERNAME\.wslconfig:3
wsl: The wsl2.localhostForwarding setting has no effect when using mirrored networking mode.

This is as a result of the extra wslconfig settings, removing it totally removed the logs and everything still work as expected.

Also I'm curious about your AI development flow, I couldn't help but notice places it was used, if you can share (publicly or privately) I will be glad. Again thank you for the project.

[geodro]

Released the docs for WLS support in beta with an additional wsl:setup command to automate the setup