BEYOND DOCKER

Kiri on Windows

On Windows, Kiri runs its Linux engine inside WSL2, on the Linux kernel Windows already ships. A small Windows program, kiri-win.exe, serves the Docker API on a named pipe for the docker CLI in PowerShell, and is also Kiri’s window and tray icon.

How it fits together

There are two halves. In WSL, the x86-64 Linux build of Kiri runs as a daemon on its unix socket, /var/lib/kiri-daemon/.kiri/run/docker.sock, exactly as on a Linux host. On Windows, kiri-win.exe listens on \\.\pipe\kiri, which the kiri docker context names as npipe:////./pipe/kiri.

Between them is one long-lived process: wsl.exe -u root -- kiri bridge. kiri-win.exe writes every Docker connection into its stdin, multiplexed as small frames (open, data, half-close, close), and kiri bridge relays each one to the daemon’s socket and sends the replies back on stdout.

WindowsWSL2 distrodocker.exekiri-win.exethe pipe, the window, the tray\.\pipe\kiria connection per commandkiri daemonsystemd, or started at WSL bootkiri bridgeone per kiri-win, run by wsl.exedocker.socka connection eachwsl.exestdin / stdout
The path a docker command takes on Windows. Every connection shares one wsl.exe process, and half-closes travel as frames of their own.

Why not TCP

The obvious way to reach a daemon in WSL is a TCP port through WSL’s localhost relay. Kiri doesn’t use it, because that relay drops TCP half-closes. docker run and docker attach depend on them: the CLI says “I’ve finished sending” while still waiting for output, and without the half-close docker run loses its output. The named pipe is message-mode, like Docker’s own \\.\pipe\docker_engine, so half-closes survive on the Windows side, and the bridge carries them as frames of their own.

A side effect: Kiri needs no change to WSL’s or Windows’ network settings, and no ports opened.

Install with the MSI

Kiri-<version>-x86_64.msi is a per-user installer, so it doesn’t ask for an administrator. It puts the engine for WSL, kiri-win.exe, the docker CLI, Compose and buildx in %LOCALAPPDATA%\Kiri, and adds Kiri to the Start menu. You need Windows 10 or 11 on x64.

When you open Kiri the first time, its window walks you through setup, and picks up where it left off after a restart:

  1. WSL, if you don’t have it: downloaded with progress, installed after one administrator approval, then a restart.
  2. A Linux for Kiri: Kiri Linux, a small Alpine-based distro that comes in the installer and is registered as kiri, or Ubuntu, downloaded.
  3. The engine, installed into that distro and started.
  4. The Docker tools: the docker CLI, Compose and buildx (each checked against its pinned SHA-256), docker build on Kiri, and, if you choose, Kiri as docker’s default engine.

Kiri’s bin folder goes at the end of your user PATH, so a docker CLI you already have (Docker Desktop’s, for example) keeps winning. When Kiri isn’t the default, use docker --context kiri, or docker context use kiri to switch.

In Kiri Linux, WSL interop is off: nothing in that distro can start Windows programs.

Install with kiri.ps1

kiri.ps1, in the same folder as the release bundle (kiri-windows-x86_64), installs the same files without an MSI, into a WSL distro you name:

PowerShell
> powershell -ExecutionPolicy Bypass -File kiri.ps1 -Distro Ubuntu
Kiri is docker's default engine: docker run --rm alpine echo hello

It runs the engine’s install script inside the distro as root (a systemd unit if the distro runs systemd, otherwise a [boot] command in /etc/wsl.conf), copies kiri-win.exe and the Docker tools to %LOCALAPPDATA%\Kiri, adds a Startup shortcut so Kiri starts in the tray when you sign in, and creates the kiri context and kiri-build builder. -Default makes Kiri the default engine even with Docker Desktop installed. -Uninstall takes it all back.

Updates and removal

kiri-win.exe checks https://download.runkiri.com/latest-windows.json, downloads the new MSI in the background, and checks it against the feed’s SHA-256 and the MSI’s own upgrade code and version. The MSI isn’t code-signed, so this is the check. It installs when you choose Restart now, or when Kiri quits after Later. The engine in WSL keeps running the old build until you click Restart engine on the “Finish updating” card, which restarts it and stops running containers. See Updates.

Removing Kiri from Installed apps undoes setup: the context, builder, PATH entry and sign-in start go. If Kiri set up its own distro, that distro is unregistered and its images, containers and volumes are deleted with it. A distro of your own only loses the engine; its data stays in /var/lib/kiri and /var/lib/kiri-daemon.

© 2026 Kiri · runkiri.com