LEARN MORE

Install

Kiri for Mac is one app, Kiri.app. Opening it the first time sets up the kiri and docker commands, a kiri Docker context and a login item that starts the engine. Nothing another Docker engine owns is changed, so you can keep OrbStack or Docker Desktop installed while you try it.

Requirements

A Mac with Apple Silicon (M1 or later). Intel Macs aren’t supported.
macOS 14 Sonoma or later.

That’s all. Kiri brings its own Linux VM, and the full download brings the docker CLI, Compose and buildx too.

Kiri or Kiri Lite

There are two disk images on the download page. The engine, the window and the menu bar are the same in both. The difference is the Docker tools.

	`Kiri-<version>.dmg`	`Kiri-Lite-<version>.dmg`
Engine, window, menu bar	Yes	Yes
`docker` CLI, Compose, buildx	Inside the app	Downloaded on first open, unless the Mac already has a `docker` CLI
Pick it if	You want `docker run` to work straight after installing	You already have a `docker` CLI, or want a smaller download

Kiri Lite downloads the same versions the full app bundles. Each file is checked against a pinned SHA-256 before it’s put in place, in ~/Library/Application Support/Kiri/cli. The download goes through the proxy in Settings → Network, if you set one.

First open

Open the disk image and drag Kiri to Applications.
Open Kiri from Applications. It sets itself up quietly (see below), starts the VM and stays in the menu bar.
Kiri asks once whether containers should get names like myapp.kiri.local. That needs an administrator password, because it adds /etc/resolver/kiri.local. If you say no, containers still answer at <name>.kiri.localhost, which needs no setup. You can change it later in Settings → Domains. See Domain names.
Open a new Terminal window, so your shell picks up the new PATH, and run something:
```
kiri run --rm hello-world
```

On a Mac with no other Docker engine (no OrbStack or Docker Desktop, no /var/run/docker.sock), Kiri also becomes docker’s default context, so plain docker run uses it. Otherwise your current context stays as it is, and you use Kiri with docker --context kiri, docker context use kiri, or the kiri command, which always talks to Kiri whatever context is selected.

What gets installed where

First open runs kiri setup. Here’s everything it touches:

Where Kiri puts things on your Mac. Everything is in your home folder except the app, and /etc/resolver/kiri.local, which only appears if you choose .kiri.local names.

What	Where
The app	`/Applications/Kiri.app`
`kiri` and `docker` commands	Links in `~/.kiri/bin`, added to the end of `PATH` by a marked line in `~/.zprofile` (and `~/.bash_profile` or `~/.config/fish/conf.d/kiri.fish` if you use bash or fish). A `docker` you already have keeps priority.
Compose and buildx	Added to `cliPluginsExtraDirs` in `~/.docker/config.json`
Docker context	`kiri`, pointing at `unix://$HOME/.kiri/run/docker.sock`
Build builder	`kiri-build`, buildx’s docker-container driver on the `kiri` context, loading what it builds into Kiri
Login item	LaunchAgent `dev.kiri.daemon` in `~/Library/LaunchAgents/dev.kiri.daemon.plist`, which runs the app’s `kiri daemon` at login and restarts it if it crashes
Engine log	`~/.kiri/daemon.log`
Settings	`~/.kiri/vm.json`, `ui.json`, `proxy.json`. See Settings.
Images, volumes, the VM’s disk	`~/Library/Application Support/Kiri` (`KIRI_DATA_DIR` moves it)
`*.kiri.local` names	`/etc/resolver/kiri.local`, only if you turn them on

Kiri never touches /usr/local/bin/docker or /var/run/docker.sock.

Install from the terminal

If you’d rather not use the disk image, one command downloads the full app, checks it and sets it up:

curl -fsSL https://runkiri.com/install.sh | bash

The script checks that the Mac has Apple Silicon and macOS 14 or later, reads the release feed at download.runkiri.com/latest.json, and downloads the release. It refuses to install anything if the SHA-256 doesn’t match the feed, if the app’s signature doesn’t verify, or if macOS doesn’t accept its notarization. Then it puts Kiri.app in /Applications (or ~/Applications if /Applications isn’t writable) and runs kiri setup --no-domains.

zsh

$ curl -fsSL https://runkiri.com/install.sh | bash
Downloading Kiri 0.1.0…
######################################################################## 100.0%
Installed /Applications/Kiri.app
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`)

Kiri 0.1.0 is ready. Open a new terminal window, then try:
  kiri run --rm hello-world
Open Kiri from Applications for the window and menu bar.

Three variables change what it does: KIRI_APP_DIR picks the folder for the app, KIRI_SKIP_SETUP=1 leaves out kiri setup, and KIRI_FEED points at a different release feed.

You can also run setup yourself at any time. kiri setup --use makes kiri the current docker context even when another engine is around, --no-agent skips the login item, and kiri setup --domains only turns on *.kiri.local.

Uninstall

kiri setup --uninstall takes back exactly what setup added: it stops and removes the LaunchAgent, removes the kiri context (only if it still points at Kiri’s socket), unsets it as the current context, takes Compose and buildx out of the docker config, removes the kiri-build builder, the links in ~/.kiri/bin and the lines in your shell profiles, and /etc/resolver/kiri.local if it’s there (macOS asks for your password for that one).

zsh

$ kiri setup --uninstall
removed the LaunchAgent
removed docker context `kiri`
removed ~/.kiri/bin from shell profiles
Kiri's data stays in ~/Library/Application Support/Kiri; delete it to remove images and volumes too

Then quit Kiri and move Kiri.app to the Bin.

Quick startYour first containers on Kiri.UpdatesHow Kiri keeps itself up to date.LinuxInstall Kiri on a Linux host, with no VM.