GET STARTED

Quick start

This page takes you from a download to a running container in a few minutes. You need a Mac with Apple silicon (M1 or later) on macOS 14 Sonoma or later.

Install and open Kiri

  1. Download Kiri from runkiri.com/download. The disk image is signed and notarized. It carries the docker CLI, Compose and buildx, so you don’t need anything else. (If you already have a docker CLI, Kiri Lite is the engine alone.)

  2. Drag Kiri to Applications and open it from there.

  3. Let Kiri set itself up. The first time it opens, Kiri runs the same steps as kiri setup, without asking:

    • adds a kiri docker context that points at ~/.kiri/run/docker.sock
    • adds a LaunchAgent, dev.kiri.daemon, so the engine starts at login
    • puts docker and kiri in ~/.kiri/bin and adds that folder to the end of your PATH in ~/.zprofile (and bash’s or fish’s profile if you use them), so a docker you already have keeps priority
    • makes kiri docker’s default context, but only if there’s no other Docker engine on the Mac
    • creates a buildx builder, kiri-build, so docker build runs on Kiri

  4. Choose how to reach your containers. The window asks once:

    • localhost: by port, like localhost:8080. Nothing to set up.
    • .kiri.local: by name, like myapp.kiri.local, with no ports. macOS asks for an administrator password, once, so Kiri can add /etc/resolver/kiri.local. Kiri never sees the password.

    You can change this later in Settings → Domains. Either way, every container also answers at <name>.kiri.localhost, which needs no setup.

Open Kiri.appkiri setupYour home folder, no passworddocker contextkiriLaunchAgentdev.kiri.daemonon PATH, after yours~/.kiri/binbuildx builderkiri-build/etc/resolver/kiri.localonly if you pick .kiri.local; macOS asks for the passwordat onceyou choose
On first open, setup changes only your own files and docker's config. The one system file, for .kiri.local names, waits for your choice and your password.

Run your first container

Start nginx in the background and publish its port 80 on 8080:

zsh
$ docker run -d --name web -p 8080:80 nginx
Unable to find image 'nginx:latest' locally
latest: Pulling from library/nginx
Digest: sha256:…
Status: Downloaded newer image for nginx:latest
3f1c9a7e2b84d06c5e1fa0b2c7d9e4a1f6b3c8d2e5a7f9b1c4d6e8a0b2c4d6e8
$ docker ps
CONTAINER ID   IMAGE   COMMAND                  CREATED         STATUS         PORTS                  NAMES
3f1c9a7e2b84   nginx   "/docker-entrypoint.…"   4 seconds ago   Up 3 seconds   0.0.0.0:8080->80/tcp   web

The first docker command starts the VM if it’s asleep. That takes a fraction of a second.

Open it by name

The container is now on localhost:8080, and also at its name:

zsh
$ open http://web.kiri.localhost   # always works
$ open http://web.kiri.local       # if you chose .kiri.local
$ open http://localhost:8080       # by port

You don’t type a port. Kiri listens on port 80 on your Mac and sends web.kiri.local straight to the container’s own HTTP port, nginx’s 80 here, so a name works even without -p. See Domain names, and HTTPS for https:// on the same names.

Start a Compose project

Compose works as it does anywhere else. Save this as compose.yaml in a folder called shop:

services:
  web:
    image: nginx
    ports:
      - "8081:80"
  redis:
    image: redis:7

Then bring it up:

zsh
$ cd shop
$ docker compose up -d
[+] Running 3/3
 ✔ Network shop_default    Created
 ✔ Container shop-redis-1  Started
 ✔ Container shop-web-1    Started
$ open http://web.shop.kiri.local

Each Compose service answers at <service>.<project>.kiri.local. The project name is the folder’s name unless you set one. More in Compose.

See it in the window

Everything you start from the terminal appears in Kiri’s window straight away. The Compose project is one group you can start, stop or remove together. A container you can reach by name shows its address and an Open button. Click a container’s name for its details, live logs, a terminal and its files.

Kiri
ContainersImagesVolumesNetworksSettings

Containers

webweb.kiri.localUp 2 min8080→80OpenStop⋯
shopCompose · 2 of 2 runningStop all⋯
webweb.shop.kiri.localUp 20 s8081→80OpenStop⋯
redisredis:7Up 20 sStop⋯
Kiri 0.1.4Linux VM running · 3 of 3 running · docker → kiri
The window after this page: the shop project grouped, and web reachable by name. The status bar shows the VM and where docker points.

Close the window and Kiri stays in the menu bar. With nothing running, the VM sleeps after a minute and gives its memory back to macOS; the next docker command wakes it. See Memory and sleep.

Next

Moving from Docker DesktopBring your images, volumes and containers over.The windowLogs, terminals and files for each container.Command line and CIThe kiri command and its subcommands.

© 2026 Kiri · runkiri.com