Mr.PlanB Logo

    Newsletter

    Subscribe our newsletter

    Get new infrastructure guides, comparison reports, and migration notes in your inbox.

    Infrastructure notes, guides, and new tools. Unsubscribe anytime.

    Back to Blog
    Docker
    Kubernetes
    Homelab
    Containers

    Kiri container runtime: a small Docker Desktop alternative for Proxmox homelab work

    November 14, 2026
    6 min read

    The Kiri container runtime is an open-source engine written in Rust designed as a lightweight local alternative to Docker Desktop and OrbStack. It speaks the Docker Engine API, allowing homelab builders to spin up containers, test complex Compose setups, and launch local single-node Kubernetes clusters on a workstation before moving production workloads to a Proxmox server.

    The project takes its name from the Igbo word ntakịrị, meaning small. Released under the Apache-2.0 license, Kiri appeared on GitHub on 2 November 2026. According to the GitHub API on 14 November 2026, the project reached about 2,565 stars, with the repository page displaying 2.6k stars and 150 forks after twelve days of public availability.

    Where Kiri fits for a Proxmox homelab

    Most Proxmox users already run Docker somewhere on the lab, in a VM or in LXC, a choice we covered in Docker in LXC vs VMs on Proxmox. Drafting a new multi-service stack straight on the lab host is slower than doing it on the machine in front of you.

    Kiri belongs on that machine (such as an Apple silicon Mac, a Windows laptop running WSL 2, or a Linux workstation). It lets you assemble your application stacks, verify network routing, and test cluster definitions locally using familiar commands. Once your Compose files and manifests work cleanly, you can transfer those exact files to your homelab infrastructure.

    The Kiri documentation and README do not mention Proxmox anywhere. On Linux, Kiri runs straight on the host kernel rather than through an auxiliary hypervisor layer. We have not tested running Kiri nested inside a Proxmox LXC container or inside a Proxmox guest VM. For now, homelab users should treat Kiri strictly as a developer runtime for your laptop or workstation, keeping standard container runtimes on your lab hosts. If you want containers on the Proxmox host side, our notes on Proxmox 9.1 OCI containers cover what the hypervisor itself offers.

    Architecture: custom kernel and Rust agent

    Kiri keeps the stack short. On macOS and Windows, Kiri runs containers in one small Linux VM with a custom 10 MB kernel (the guest kernel is Linux, GPL-2.0). The PID 1 process inside this guest is an independent Rust agent measuring approximately 900 KB. This guest agent communicates with the host system over vsock and starts containers directly using a single clone3 system call into isolated namespaces and a cgroup.

    The README says there is no runc, no shim and no dockerd in that path. The README puts the daemon at about 15 MB. The VM automatically sleeps after 60 seconds of idle time, and the README states that it wakes back up in about 0.15 seconds when a new command arrives.

    For network endpoints, Kiri provides automatic local domains formatted as http://<name>.kiri.local, complete with automatic HTTPS issued by its internal certificate authority. The desktop interface and setup tools are localized into 38 languages across macOS, Windows, and Linux, including right-to-left layout support for Arabic, Persian, and Central Kurdish.

    The benchmark claims

    The project authors published speed comparisons measuring the time needed for an Alpine Linux container to run true and exit, with the container removed immediately after execution. The project states these numbers reflect the median of 30 test runs using the same Docker CLI across all engines.

    Per the Kiri repository documentation on 14 November 2026, the median execution times are:

    • Through the Docker Engine API: Kiri clocked at 2.55 ms, compared to 213 ms for Docker Desktop and 380 ms for OrbStack.
    • Through the docker CLI: Kiri clocked at 14.2 ms, compared to 243 ms for Docker Desktop and 442 ms for OrbStack.

    The project hosts its full methodology and dataset inside bench/results.json within the source repository, and users can execute kiri bench to inspect the results locally. Readers should remember these figures are the project's own internal metrics, recorded on an early software build.

    Installation and quick start

    Installing Kiri uses platform packages distributed through runkiri.com:

    • macOS 14+ (supporting both Apple silicon and Intel chips): Download the .dmg package installer.
    • Windows 10 and 11 (supporting x86-64 and Arm via WSL 2): Download the .msi installer.
    • Linux distributions (Ubuntu, Fedora, and compatible derivatives): Install via .deb or .rpm packages. On 3 November 2026, release v0.1.15 added signed repositories for apt and dnf using the release archive key kiri-archive-key.asc.

    The first time you open Kiri, it automatically configures a dedicated kiri Docker context. Kiri also includes a built-in update mechanism that checks software signatures before applying updates.

    You can interact with Kiri through standard Docker syntax by specifying the context:

    docker --context kiri run --rm alpine echo hello
    docker --context kiri compose up -d
    

    Every command can also run directly through the kiri CLI binary:

    kiri run --rm alpine echo hello
    kiri compose up -d
    

    If you want to migrate existing homelab experiments off another desktop app, Kiri provides a dedicated import command:

    kiri import
    

    This single command brings images, volumes, and existing containers over from OrbStack or Docker Desktop. If you run into compatibility challenges or prefer alternative command-line engines, check our breakdown on Podman vs Docker in practice.

    Beyond single containers, Kiri provides a one-command Kubernetes cluster:

    kiri k8s start
    

    This command provisions a single-node Kubernetes cluster and switches your active kubectl context to kiri. According to the v0.1.18 release notes published on 6 November 2026, Kubernetes pods can attach your local folders through hostPath volumes, mapped at /Users on macOS, /mnt/c and /mnt/d on Windows, and /home on Linux. You can also spawn separate virtual environments using kiri machine create dev --distro ubuntu followed by kiri machine shell dev.

    Hardware passthrough and recent updates

    On 10 November 2026, the developers published Kiri release v0.2.0. This release introduced beta support for mounting USB devices directly into containers across macOS, Windows, and Linux. When you plug in a serial adapter, a Zigbee stick, or related hardware, Kiri displays where the device node sits inside the Linux environment and generates the exact --device parameter to copy into your run command. This is especially practical for anyone testing Home Assistant or Zigbee gateway containers locally before deploying them to long-term hardware.

    The same release runs amd64 builds on Apple silicon through Rosetta, so bun install no longer crashes, lets docker load take images saved by Podman, stops the Linux window from flickering, and lets container names answer on ports you choose in Settings, Domains.

    Earlier updates leading up to v0.2.0 added practical polish:

    • Release v0.1.18 (6 November 2026) added a built-in terminal window with tabs and splits, allowed unprivileged users to bind ports below 1024, and enabled container firewall tooling like nftables, iptables, and IPVS.
    • Release v0.1.17 (3 November 2026) stripped credentials, authentication tokens, PEM keys, and URL passwords out of diagnostic logs prior to sending crash reports.
    • Release v0.1.14 (2 November 2026) made a fresh install quiet: nothing downloads until you use it, and the build engine (BuildKit) is fetched the first time you build.

    Early project caveats

    The project is roughly 12 days old. The code sits at version 0.2.0, which means breaking changes, missing edge cases, and architectural shifts are probable over the coming months.

    All benchmark results and startup speeds are the project's own numbers from a single Alpine test case. A stack with databases, logging and volume mounts will behave differently.

    The roadmap notes that a built-in builder is still in progress. The team plans to serve Docker build endpoints natively so buildx can use its standard docker driver against Kiri, enabling BuildKit features like host-gateway. Our take: try Kiri on the laptop where you draft Compose files and test small Kubernetes manifests, and keep the lab's own Docker hosts on Proxmox as they are until the project has a few more releases behind it. We will check back once the built-in builder ships.

    Frequently Asked Questions

    What is Kiri container runtime?

    Kiri is an open-source container engine written in Rust that speaks the Docker Engine API. It runs containers inside a small virtual machine on macOS and Windows, or directly on the host kernel on Linux, serving as a lightweight alternative to Docker Desktop and OrbStack.

    Does Kiri replace Docker on a Proxmox server?

    No. Kiri is designed for desktop workstations and laptops running macOS, Windows, or Linux. The official project repository does not mention Proxmox VE, and running Kiri nested inside a Proxmox virtual machine or LXC container is completely untested.

    Can Kiri run single-node Kubernetes clusters locally?

    Yes. Kiri includes a built-in single-node Kubernetes cluster that starts with the command kiri k8s start. It sets up a dedicated kubectl context and mounts local directories through hostPath volumes.

    How does Kiri pass USB devices to containers?

    Starting in release v0.2.0 on 10 November 2026, Kiri includes beta support for passing USB hardware like serial adapters and Zigbee sticks directly into containers on macOS, Windows, and Linux, providing the exact flag to copy.