DOCKER

Moving from Docker Desktop

Kiri speaks the same Docker Engine API as Docker Desktop, so the docker CLI, Compose and buildx work against it unchanged. Your Dockerfiles, Compose files and scripts carry over as they are. What doesn’t move by itself is what lives inside Docker Desktop’s VM: its images, volumes and containers. Kiri can copy those over for you, and you can keep Docker Desktop installed and switch between the two.

What changes, and what doesn’t

The docker command picks an engine through its current context. Docker Desktop’s is desktop-linux, behind ~/.docker/run/docker.sock. Kiri’s is kiri, behind ~/.kiri/run/docker.sock. Moving is mostly a matter of which context docker uses.

The same docker CLI, before and after. Switching the context changes which socket, and so which engine and which images, every docker, compose and buildx command reaches.

Carries over as it is	Needs copying, or pulling again
Dockerfiles, Compose files, scripts	Images
`host.docker.internal`, `-p`, `-v`, networks by name	Named volumes and their data
Registries you log in to with `docker login`	Containers

Bring your images, volumes and containers

kiri import copies from Docker Desktop to Kiri through the docker CLI, so each engine answers through its own API. Docker Desktop has to be running while it copies; nothing in it is changed or removed.

Images go across with docker save from Docker Desktop and docker load into Kiri. Only tagged images are listed.
Named volumes are read by a short-lived, read-only helper container on Docker Desktop and written by another on Kiri, as a tar stream, so file owners and permissions survive. Both helpers remove themselves. The helper needs an alpine or busybox image in Docker Desktop. Anonymous volumes (64-character names) are left out.
Containers are made again in Kiri from Docker Desktop’s inspect: command, entrypoint, environment, labels, ports, mounts, restart policy, limits, capabilities and networks. A missing network is created first, and a missing image is copied first. They arrive stopped.

Anything Kiri already has by the same name is skipped. Name the source, since kiri import on its own reads from OrbStack:

zsh

$ kiri import desktop-linux --list
images:
  nginx:alpine
  postgres:17
  alpine:latest  (already in Kiri)
volumes:
  shop_pgdata
containers:
  shop-db-1
$ kiri import desktop-linux
image nginx:alpine: done
image postgres:17: done
volume shop_pgdata: done
container shop-db-1: done

To copy one thing, name it: kiri import desktop-linux image postgres:17, … volume shop_pgdata or … container shop-db-1.

The window does the same. When Docker Desktop is running and has things Kiri doesn’t, a strip under the lists says how many, with Review to pick what to copy. Settings → Import has the same lists at any time, with Docker Desktop and OrbStack as sources. See The window.

Switch the context

When you install Kiri on a Mac that has Docker Desktop, it adds the kiri context but leaves your current context alone, so docker keeps talking to Docker Desktop until you choose. The status bar at the bottom of Kiri’s window says which engine docker uses: docker → kiri or docker → desktop-linux.

Make Kiri the default for docker, Compose and buildx:
```
docker context use kiri
```
kiri setup --use does the same.
Check where commands go now. docker context ls marks the current context with *, and docker info names the engine it reached.
To go back to Docker Desktop:
```
docker context use desktop-linux
```

For one command, skip the switch: docker --context kiri ps, or kiri ps, which always reaches Kiri whichever context is current.

Running both side by side

Kiri and Docker Desktop can be installed and running at the same time. Kiri keeps out of Docker Desktop’s way:

It doesn’t touch /var/run/docker.sock or /usr/local/bin/docker.
Its own docker goes in ~/.kiri/bin, added to the end of PATH, so the docker you already have keeps priority.
It only makes kiri the default context on a Mac with no other Docker engine.
Its images, volumes and VM disk are its own, in ~/Library/Application Support/Kiri.

The two engines share your Mac’s ports. If a container in each publishes the same host port, only the first gets it, so stop one side’s container, or publish a different port. Each engine has its own VM, so running both costs the memory of both. Kiri gives its VM’s memory back when it sleeps, after a minute with nothing running.

Differences to expect

Kiri covers what the docker CLI, Compose and buildx use day to day, but it isn’t Docker Desktop.

Area	On Kiri
The socket	`~/.kiri/run/docker.sock`, never `/var/run/docker.sock`. A tool that only looks for `/var/run/docker.sock` needs `DOCKER_HOST=unix://$HOME/.kiri/run/docker.sock`.
Builds	`docker build` goes through BuildKit in a Kiri container, the `kiri-build` builder (buildx’s docker-container driver), which loads what it builds into Kiri and stops when idle. See Builds.
Kubernetes	`kiri k8s start` runs a single-node k3s cluster, as the `kiri` kubectl context. See Kubernetes.
Local names	Containers answer at `http://<name>.kiri.local` once you turn it on, or `http://<name>.kiri.localhost` with no setup. See Domain names.
amd64 images	Run through Rosetta; `--platform` is honoured. See Images and Rosetta.
Network modes	`--network container:<name>` isn’t supported yet. `bridge`, `host`, `none` and your own networks are.
Mounts	Bind mounts, volumes and `tmpfs`. Other `--mount` types are refused.
Everything else	An Engine API call Kiri doesn’t have answers with “Kiri does not support … yet”, so you see exactly what’s missing.
The Mac	Apple Silicon only.

If something you rely on isn’t there, tell us with Feedback in Kiri’s window.

Kiri and Docker DesktopSide by side, feature by feature.Command line and CIEvery kiri command and the socket.ComposeProjects, names and the window’s groups.