GET STARTED

Questions

Short answers to the questions people ask most, each with a link to the page that has the details. Something missing? Ask with Feedback in Kiri’s window.

Your Mac

Does Kiri need Apple silicon?

Yes. Kiri for Mac needs an Apple silicon Mac (M1 or later) on macOS 14 Sonoma or later. It runs its Linux VM with Apple’s Virtualization.framework, and its guest kernel and agent are built for arm64.

Will it run on an Intel Mac?

No. Intel Macs aren’t supported, and the install script stops with “Kiri needs an Apple silicon Mac (M1 or later).” On an Intel PC, see Kiri on Linux or Kiri on Windows.

Can I run x86 (amd64) images?

Yes. Kiri shares Rosetta into the VM, so linux/amd64 images run on Apple silicon, and --platform linux/amd64 is honoured. Rosetta has to be installed on the Mac; if it isn’t, softwareupdate --install-rosetta adds it. See Images and Rosetta.

Where does Kiri keep its data?

Path What’s there
~/Library/Application Support/Kiri images, volumes, container records and the VM’s disk (vm/data.img). KIRI_DATA_DIR moves it.
~/.kiri the socket (run/docker.sock), settings (vm.json, ui.json), the docker and kiri commands (bin/), certificates (tls/) and the daemon’s log
~/Kiri the running containers’ files, for Finder (read-only)
~/Library/LaunchAgents/dev.kiri.daemon.plist starts the engine at login

Kiri doesn’t touch /usr/local/bin/docker or /var/run/docker.sock.

Docker Desktop and OrbStack

Does Kiri replace Docker Desktop?

For running containers from the docker CLI, Compose and buildx, yes. Kiri serves the Docker Engine API, so your commands, Compose files and scripts don’t change. It brings its own docker CLI, and kiri import copies your images, volumes and containers over from Docker Desktop or OrbStack. See Moving from Docker Desktop and the comparison.

Can I keep Docker Desktop installed?

Yes. Kiri adds its own kiri docker context and leaves everything else alone:

  • If Docker Desktop or OrbStack is on the Mac, docker’s default context stays as it was. Switch with docker context use kiri and back with docker context use default.
  • ~/.kiri/bin goes at the end of your PATH, so a docker CLI you already have keeps priority.
  • kiri run, kiri ps, kiri compose up and the other kiri versions of docker’s commands always go to Kiri, whatever context is selected.

The status bar of Kiri’s window shows which engine docker uses right now (docker → kiri).

Memory and the VM

How much memory does Kiri use?

The engine itself is small: the kiri daemon on the Mac and the agent in the VM measured 9.7 MB together, against 216 MB for OrbStack’s dockerd and containerd. Kiri also has no per-container shim process. Your containers use what they need inside the VM, and a balloon gives memory they free back to macOS.

Resident memory of each engine's own processes, before any container memory. From bench/results.json, measured on one Apple silicon Mac.

You set the most the VM may use in Settings → Resources. See Memory and sleep.

Why does the VM go to sleep?

Because sleeping is the only way to give all of its memory back. Apple’s balloon device takes pages from the guest but doesn’t release every one to macOS, so when nothing is running for 60 seconds, Kiri powers the VM off. The VM boots again in about 0.15 s, so the next docker command barely notices.

The VM never sleeps while a container or exec is running. The window’s own status requests don’t count as use, so an open window doesn’t keep it awake. KIRI_IDLE_SECS changes the 60 seconds, and 0 turns sleep off.

awake: containers runningawake, idle: 60 sasleep: 0 MBawakelast container stopsVM powers offdocker runwakes in ~0.15 s
The VM sleeps only when nothing runs. Any docker command wakes it.

Privacy and licence

Does Kiri collect telemetry?

No. There is no analytics or usage reporting in the app or the engine. Kiri goes online for things you’d expect it to:

  • Updates: the window checks download.runkiri.com/latest.json once each time it opens, and when you choose Check for Updates….
  • Images: pulls, pushes and logins go to the registry you name. The Pull box searches Docker Hub as you type.
  • Kiri Lite: on first launch it downloads the pinned docker CLI, Compose and buildx from Docker and GitHub, unless the Mac already has a docker CLI.
  • Kiri Share: only when you run kiri share, which connects to edge.runkiri.com.

Feedback in the window opens a page in your browser; nothing is sent until you submit it there.

What licence is Kiri under?

Kiri’s code is dual-licensed under the MIT licence or Apache License 2.0, at your option. The guest kernel is Linux, under GPL-2.0. The name “Kiri” and its logo aren’t covered by those licences: a fork is welcome, under a different name and logo.

Other platforms and removal

Does Kiri run on Windows or Linux?

On Linux, yes, and with no VM: the engine runs on the host’s kernel, packaged as .deb and .rpm. See Kiri on Linux. On Windows, Kiri is experimental: it runs the engine in a WSL2 distro behind its own window and installer. See Kiri on Windows.

How do I uninstall Kiri?

  1. If you turned on HTTPS, turn it off first in Settings → Domains. That removes Kiri’s certificate authority from your keychain.
  2. In a terminal, run kiri setup --uninstall. It removes the LaunchAgent, the kiri docker context (and makes docker forget it as the default), the kiri-build builder, ~/.kiri/bin and its line in your shell profiles, and /etc/resolver/kiri.local (macOS asks for your password for that one).
  3. Quit Kiri from the menu bar and move Kiri.app to the Bin.
  4. To remove your images, volumes and the VM’s disk too, delete ~/Library/Application Support/Kiri. Settings and certificates are in ~/.kiri.

© 2026 Kiri · runkiri.com