> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run builds on Windows

> Isolated builds on a Windows machine need Docker Engine inside WSL2, not Docker Desktop.

On Windows the runner runs inside WSL2. For isolated builds, Docker Engine
must run inside WSL2 too. Docker Desktop is not enough. With it alone,
`outerlayer runner init` refuses unless you pass `--allow-process-builds`.
Builds then use `builtin:process`, record `shared-user`, and are not
isolated. See [The process fallback](/write-your-own-hooks#the-process-fallback).

## Set it up

1. In a WSL2 shell, install and start Docker Engine 26 or later, following
   Docker's instructions for your Linux distribution. Install Docker's
   Buildx plugin too, version 0.18 or later. The runner builds images with
   it; see [Image builds](/run-a-host-as-a-service#image-builds).

2. Check the shell and the engine:

   ```bash theme={"system"}
   # Prints a line: this shell is WSL2.
   grep -i microsoft /proc/version
   # Does not print "Docker Desktop".
   docker info --format '{{.OperatingSystem}}'
   # Prints 26 or later.
   docker version --format '{{.Server.Version}}'
   ```

3. From the same shell, follow [Set up a host](/set-up-a-host).
   `outerlayer runner init` names `builtin:container` when it finds Docker
   Engine in WSL2. Otherwise it refuses and says what is missing;
   `--allow-process-builds` names `builtin:process` instead, with no isolation.

4. Run `outerlayer doctor`. The `Build isolation` line should say
   `builtin:container`.

## Keep the runner running

WSL2 shuts a distribution down once no Windows program is using it, so the
runner would stop when you close your terminals or log out.
`outerlayer runner init` sets up what prevents that. You write no service
file, and the command is the same as on Linux.

* It writes the systemd unit inside WSL2 and enables it.
* It makes a Windows scheduled task that starts the distribution when you log
  in and keeps it running, with `schtasks.exe` through WSL2's Windows
  interop. The task has the unit's name, `outerlayer-runner`. The runner runs
  from when you log in, not before. For a host that runs before anyone logs
  in, use Linux.

If systemd is off in the distribution, setup turns it on in `/etc/wsl.conf`
and stops there. Run `wsl --shutdown` once from Windows, open the
distribution again, and run `outerlayer runner init` or
`outerlayer runner install --service` again. Setup makes no unit and no task
until then.

If interop is off, setup prints the `schtasks` command to run in Windows.
It does the same under `sudo`, which drops `WSL_DISTRO_NAME`, the variable
that names the distribution. Run setup without `sudo` so it can make the
task. To remove the unit and the task, run
`outerlayer runner uninstall --service`.
See [Run a host as a service](/run-a-host-as-a-service).

## What doctor says

| The machine has | `outerlayer doctor` reports |
| - | - |
| Docker Engine in WSL2, hooks `builtin:container` | Isolation `container`. |
| Docker Desktop only, hooks `builtin:process` | Isolation `shared-user`, and the fix: install Docker Engine 26 or later in place of Docker Desktop, and set `runner.hooks.provision` and `runner.hooks.cleanup` to `builtin:container`. |
| Docker Desktop, hooks `builtin:container` | A failure: every build would fail at provision. The fix is Docker Engine inside WSL2, or `builtin:process`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.