BEYOND DOCKER

Linux machines

A Linux machine is a Linux system that keeps running, for the times you want a shell on a distro rather than a container for one app. It has your Mac user’s name and ID, sudo without a password, and your files under /Users at the same paths as on the Mac. Build and test in Linux on the project you have open in your Mac editor.

Create one and open a shell

$ kiri machine create dev --distro ubuntu
pulling ubuntu:24.04…
machine dev (ubuntu:24.04) is running: kiri machine shell dev
$ cd ~/code/myapp
$ kiri machine shell dev -- pwd
/Users/you/code/myapp
$ kiri machine shell dev

kiri machine shell dev opens a login shell as you: bash if the distro has it, else its sh. It starts in the folder you ran it from when that’s under /Users, else in your home folder. Put a command after -- to run it instead of a shell.

Without --distro, a machine is Ubuntu. A name is letters, digits and dashes.

Distros

Any other image works too: kiri machine create box --image IMAGE, or a name --distro doesn’t know, which is used as the image.

Your user, sudo and files

When a machine starts, Kiri makes sure it has:

• Your user, with the same name and the same uid and gid as on the Mac, so files you create under /Users belong to you on both sides.
• sudo without a password, through /etc/sudoers.d/kiri. Slim images that come without sudo get it installed in the background on first start, so it may take a moment to appear.
• /Users from your Mac, read-write, at /Users. Your home is /Users/<you>, so the shell reads the same dotfiles as on the Mac.

Only /Users is mounted. Other Mac folders, such as /opt or /Volumes, aren’t visible in a machine.

systemd

By default a machine runs a small loop as its first process, which is enough for shells and builds. If you need services that systemd manages, ask for it as the init:

kiri machine create web --distro debian --systemd

With --systemd, the machine runs privileged, with its own /run, /run/lock and /tmp in memory, and Kiri installs systemd first if the image lacks it. Alpine has no systemd, so --systemd doesn’t work there.

All the commands

$ kiri machine list
NAME             IMAGE                        STATE
dev              ubuntu:24.04                 Up 5 minutes

A machine is a container

Under the hood, a machine is a Kiri container named machine-<name>, with the restart policy unless-stopped, so it comes back when Kiri starts unless you stopped it. It also has the NET_ADMIN and SYS_PTRACE capabilities, for tools like ip, strace and debuggers. That means the rest of Kiri works on it too: it’s in the window’s container list, its files are in Finder at ~/Kiri/machine-dev while it runs, and docker --context kiri exec machine-dev … reaches it.

© 2026 Kiri · runkiri.com