DOCKER

Images and Rosetta

Kiri pulls and pushes images on the Mac, then streams each one into its VM once and unpacks it there. The docker image commands work as usual, and images built only for amd64 run too, through Apple’s Rosetta.

Image commands

Command Notes
docker pull Uses your docker login credentials, and --platform.
docker push, tag
docker images, image inspect, rmi docker images --filter reference=….
docker save, load Image tarballs, both ways.
docker history Each step that made a layer, with its size.
docker search --limit, and --filter on is-official and stars.
docker image prune Kiri keeps no untagged images, so this frees space only with -a: every image no container uses.
docker system df Image sizes. Kiri doesn’t measure container and volume sizes here.

Pulls, pushes, search and login go through the proxy set in Settings → Network, if there is one. Kiri’s window lists images under Images, with their tag, size, when they were pulled and which containers use them.

Registries and docker login

Log in as you would with Docker. The docker CLI asks Kiri to check the password with the registry, stores the credentials itself, and sends them along with each pull and push:

docker login ghcr.io -u you
docker pull ghcr.io/you/app:1.4
docker tag app:dev ghcr.io/you/app:1.5
docker push ghcr.io/you/app:1.5

Docker Hub is the registry when an image name doesn’t give one.

amd64 images through Rosetta

Kiri’s VM is arm64, like your Mac. An amd64 image still runs: macOS shares Rosetta for Linux with the VM over virtiofs, and the VM’s kernel hands every x86-64 program to it. Rosetta translates the program to arm64 as it runs, inside the container, with nothing for you to set up per image.

macOSKiri’s VM (arm64)Rosettafor Linux/run/rosettaread-only shareamd64 containernode server.jsan x86-64 programLinux kernelbinfmt_misc: x86-64 ELF → Rosettavirtiofs1 exec2 hand over3 runs itas arm64
An amd64 binary starting in a container. The kernel recognises an x86-64 program and passes it to Rosetta, which macOS shares into the VM; the program then runs translated to arm64.

Kiri shares Rosetta with the VM only when macOS has it installed; without it, amd64 programs can’t start. Install it from Terminal:

softwareupdate --install-rosetta

Choosing a platform

Without --platform, Kiri pulls the image’s arm64 variant. When an image has no arm64 variant but has an amd64 one, and Rosetta is installed, Kiri pulls the amd64 one and says so in the pull’s output.

–platform given?has linux/arm64?has linux/amd64and Rosetta installed?that platformarm64, nativeamd64 through Rosettanonoyesyesyesno: the pull fails
Which variant docker pull fetches. Only an image with no arm64 variant falls back to amd64 on its own.

To run the amd64 variant of an image that has both, ask for it with --platform, on docker pull or docker run:

zsh
$ docker pull -q --platform linux/amd64 alpine
docker.io/library/alpine:latest
$ docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine
linux/amd64
$ docker run --rm alpine uname -m
x86_64
BuildsBuild images with BuildKit in Kiri.ContainersRun what you pulled.SettingsThe proxy, and the VM’s CPUs and memory.

© 2026 Kiri · runkiri.com