FEATURES

Command line and CI

Kiri is one binary, kiri. The app runs it for the window and the engine, and you can run it yourself: to set Kiri up, update it, start a Kubernetes cluster or a Linux machine, or run Docker’s own commands on Kiri. Nothing here needs the window, so the same engine works in a terminal session, a script or a CI job.

The commands

The app puts kiri (and its own docker) in ~/.kiri/bin and adds that folder to the end of your PATH in new terminal windows, so a docker you already had keeps priority.

On a Linux host the same binary has daemon, k8s, machine, raw and Docker’s commands, plus bridge, the WSL2 end of Kiri on Windows. setup, ui, update, import, bench and boot are Mac-only.

The kiri context and the socket

The engine listens on a Unix socket at ~/.kiri/run/docker.sock and speaks the Docker Engine API there. kiri setup (which the app runs the first time it opens) writes a docker context called kiri that points at it, the same as you’d get from:

docker context create kiri --docker host=unix://$HOME/.kiri/run/docker.sock

So there are three ways to reach Kiri from the docker CLI:

• docker --context kiri … for one command, or docker context use kiri to make it the default. On a Mac with no other Docker engine, setup makes kiri the default for you.
• DOCKER_HOST=unix://$HOME/.kiri/run/docker.sock, which wins over any context.
• kiri …, which runs the docker CLI with that DOCKER_HOST set and DOCKER_CONTEXT removed, so it always reaches Kiri.

Kiri never touches /var/run/docker.sock or /usr/local/bin/docker. Set KIRI_SOCKET to put the socket somewhere else; the daemon and every kiri command read it.

Without the window

You don’t need the window open, or ever opened, for Kiri to work. The engine is kiri daemon, and kiri setup installs a LaunchAgent, ~/Library/LaunchAgents/dev.kiri.daemon.plist, that starts it at login. launchd restarts it if it crashes and leaves it stopped after a clean exit. Its output goes to ~/.kiri/daemon.log.

$ kiri setup --no-domains
docker context `kiri` → unix:///Users/you/.kiri/run/docker.sock
docker and kiri commands: /Users/you/.kiri/bin (on PATH in new terminal windows)
kiri daemon starts at login (/Users/you/Library/LaunchAgents/dev.kiri.daemon.plist)
docker build uses BuildKit in Kiri (builder `kiri-build`)

--no-agent leaves the LaunchAgent out; then start the engine yourself with kiri daemon. If it’s already running, a second kiri daemon says so and exits. The daemon boots the VM on the first request and lets it sleep after 60 seconds idle, so leaving it running costs about 15 MB.

These environment variables change the engine. The daemon reads them when it starts:

Kiri in CI

On a Mac

Kiri boots a Linux VM, so the runner must be an Apple Silicon Mac on macOS 14 or later that can run one, such as a Mac you host yourself. In a job, install the app without its login setup, start the engine, then set up the context and builder:

On Linux

On Linux, Kiri runs on the host’s kernel with no VM, so any x86-64 runner with systemd can use it. Install the .deb or .rpm from the download page:

sudo apt install ./kiri_<version>_amd64.deb      # or: sudo dnf install ./kiri-<version>-1.x86_64.rpm

Then either run docker with sudo in the job, or add the job’s user to the kiri group with sudo usermod -aG kiri "$USER" (it takes effect in a new login session).

The package enables and starts kiri.service, which serves /run/kiri/docker.sock. The full kiri package brings its own docker, Compose and buildx and points them at that socket unless DOCKER_HOST, DOCKER_CONTEXT or a context of your own says otherwise. With kiri-lite, the engine alone, point your docker CLI at it:

export DOCKER_HOST=unix:///run/kiri/docker.sock

Without systemd, for example inside a privileged container, run kiri daemon as root yourself. It then listens on $HOME/.kiri/run/docker.sock, or on KIRI_SOCKET if you set it. More in Kiri on Linux.

© 2026 Kiri · runkiri.com