Install gon-cli on WSL2

Two installer scripts get you from a clean Windows + WSL2 box to a working gon up in a few minutes. Run the Windows one first, then the WSL2 one — that order matters because the WSL2 installer reuses the GitHub token and the mkcert root CA from the Windows side, so your Windows browsers trust the local .test certs out of the box.

Prerequisites

  • Windows 10/11 with WSL2 and a Linux distro. If you don't have one yet, run wsl --install in PowerShell as Administrator (see Microsoft's guide).
  • Docker Desktop with WSL Integration enabled for your distro: Settings → Resources → WSL Integration. Docker docs.

Step 1 — Install on Windows (host)

Open PowerShell and run:

irm https://gon.rozklad.dev/install.ps1 | iex

This installs gon-cli on Windows, sets up mkcert with a root CA in the Windows trust store, and prompts you for a GitHub Personal Access Token (PAT) which it stores for the next step.

Step 2 — Install in your WSL2 distro

Open your distro and run:

curl -sS https://gon.rozklad.dev/install.sh | bash

The WSL2 installer:

  • Detects the mkcert CA from Step 1 and shares it (so certs minted inside WSL2 are trusted by your Windows browsers without any extra import).
  • Reuses the GitHub PAT from Step 1 — no re-paste.
  • Runs gon auth:login automatically: docker login ghcr.io and the WSL2 credsStore fix in one go.
  • Installs Composer GitHub auth, Node + yarn, and MariaDB if missing.

Step 3 — Create your first project

cd ~
gon create-project myapp
cd myapp
gon up

Open https://myapp.test in your Windows browser. Mailpit is at https://mail.myapp.test. From here, follow Create a project for the wizard options.

Recommended extras

Persist /etc/hosts across WSL2 reboots

WSL2 regenerates /etc/hosts on every wsl --shutdown, which silently wipes the entries gon up writes for myapp.test. Disable that once per distro:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[network]
generateHosts = false
EOF

Then in PowerShell: wsl --shutdown. Reopen your terminal — entries now persist across reboots.

Keep projects on the WSL2 native filesystem

Always work from ~/ (e.g. /home/you/projects/), never from /mnt/c/.... Bind-mounting Windows-side files into Docker over 9P makes Laravel's autoload stat()s 5–15× slower per request. gon create-project detects this and offers to relocate, but it's good to know upfront.

Troubleshooting

First stop for any environment issue:

gon doctor

  • "Docker daemon is not running" — open Docker Desktop, wait for Engine running. gon create-project on a recent build offers Start Docker Desktop now? [Y/n].

  • error getting credentials - err: exit status 1, out: `` when pulling from ghcr.io — re-run gon auth:login; it strips the broken credsStore: desktop entry from ~/.docker/config.json and re-authenticates.

  • Hosts entries gone after Windows reboot — confirm /etc/wsl.conf contains generateHosts = false (see Recommended extras above) and that you ran wsl --shutdown after editing.