Skip to content
GRIMOIRY

Reach WSL2 from Windows

$ grim hosts:windows

On WSL2 the stack runs in Linux and the browser runs in Windows, and each side has a hosts file of its own. The entry in WSL's /etc/hosts means nothing to Edge or Chrome. Until Windows has the same line, https://shop.test does not resolve there.

grim create-project adds that line for you. This command is for the times it did not: the UAC prompt was declined, the project was cloned instead of created, or someone tidied the hosts file. grim up notices the missing line and points you here.

Usage

$ grim hosts:windows             # the project you are standing in
$ grim hosts:windows shop        # by name, from anywhere
$ grim hosts:windows --remove    # take the entry out again

Run it inside WSL2. Anywhere else it says it is WSL2-only and exits without an error.

Arguments and options

Add (or remove) project entry in the Windows hosts file from WSL2 (UAC prompt)

Usage

grim hosts:windows [--remove] [--] [<project>]

Arguments

Argument Description
project Project name (defaults to the project in cwd) (optional)

Options

Option Description
--remove Remove the entry instead of adding it

What it actually does

  1. Finds the Windows hosts file at /mnt/c/Windows/System32/drivers/etc/hosts.
  2. Settles the project name. The argument, or name from the grim.json of the project you are in.
  3. Looks for its own marker, # grim: shop. When it is there, it prints Windows hosts already contains an entry for shop. and is done.
  4. Raises a UAC prompt on the Windows desktop. Once you click Yes, an elevated PowerShell appends 127.0.0.1 shop.test mail.shop.test # grim: shop.
  5. Reads the file again to confirm the line arrived, and prints the command that opens the project in your Windows browser: cmd.exe /c start https://shop.test.

--remove works the same way in reverse. It deletes every line carrying the project's marker and leaves all other lines as they were.

Pitfalls

The prompt is on the desktop, not in the terminal

The terminal waits while a UAC window sits behind your other windows. Declined or missed, it ends with Could not update Windows hosts: Elevation completed but the entry did not appear (UAC may have been declined) and prints a one-line PowerShell command to run from an Administrator terminal instead.

A line you wrote by hand is not recognised

The check looks for the # grim: shop marker, not for the host name. With your own shop.test line in the file, grim adds its line next to it, which does no harm. --remove likewise takes out only marked lines.

The C: drive is not mounted

Windows hosts file not reachable at /mnt/c/Windows/System32/drivers/etc/hosts. means WSL2 cannot see the Windows drive at its default mount point. Restore the mount, or add the line on the Windows side by hand.

Entries vanishing from WSL's own /etc/hosts after wsl --shutdown is a different file and a different problem. WSL2 regenerates that file unless /etc/wsl.conf sets generateHosts = false under [network].

After it finishes

Open https://shop.test in the Windows browser. grim doctor confirms it with Windows hosts ✓ shop.test registered.

grim create-project

Conjure a project

Create a project directory with a grim.json on the current train and install it, or write the grim.json for an application that already runs.

grim doctor

Check your circle

Check every tool grim expects on this machine, and the project you are standing in, and say what to do about what is missing.

grim setup

Prepare the machine

Put the shared pieces of local development in place, once per machine: the Traefik proxy, a trusted local certificate authority and .test name resolution.

grim up

Raise the stack

Start the project's containers and its Vite dev server, with a trusted certificate and a working address, and say where to open it.

Recipes that use it

Install on Windows with WSL2

Run the Windows installer, then the Linux installer inside the distro, keep the distro's hosts file from being rewritten, run grim setup, and finish on a clean grim doctor.