TIPS & GUIDES

Kiri: The Ultra-Fast Rust Container Runtime Replacing Docker Desktop and OrbStack

Key Takeaways: Kiri is an open-source, Rust-based container runtime for macOS, Windows, and Linux that replaces Docker Desktop and OrbStack by spawning containers in milliseconds via a single system call while bundling local HTTPS domains, one-command Kubernetes, and free public webhook tunneling.

Modern software engineering, microservices orchestration, and local AI agent sandboxing rely heavily on containerized environments. However, traditional desktop container platforms often introduce substantial memory overhead, multi-layered daemon latency, and persistent background CPU consumption. Developers running multi-container stacks alongside resource-intensive local models frequently experience battery drain and sluggish startup cycles.

Kiri solves this infrastructure bottleneck by rethinking how containers launch on desktop and server operating systems. Built from the ground up in Rust and licensed under Apache-2.0, Kiri delivers full compatibility with the Docker Engine API while stripping away legacy middleware layers. You can explore the source code on the Kiri GitHub Repository or download platform installers directly from the Kiri Official Website.

What Is Kiri and Why Does It Outperform Traditional Runtimes?

Named after the Igbo word ntakịrị (meaning “small”), Kiri is a lightweight, cross-platform container engine designed as a drop-in replacement for Docker Desktop, OrbStack, and Colima. Because it speaks the native Docker Engine API, your existing docker CLI, Docker Compose configurations, BuildKit workflows, and IDE integrations function without modification.

Traditional container engines route every lifecycle request through a five-stage execution chain: the docker CLI communicates with dockerd, which calls containerd, which spawns a persistent containerd-shim process, which finally invokes runc to initialize the container. Every running container leaves a resident shim process consuming system memory.

Kiri eliminates that entire middleware chain. When you trigger a container run command, Kiri passes the instruction from the host daemon straight to a minimal guest agent that invokes the Linux kernel directly.

  • Sub-Millisecond API Execution: Starting and exiting an Alpine Linux container through the Docker Engine API takes a median of 2.55 milliseconds on Kiri, compared to 213 milliseconds on Docker Desktop and 380 milliseconds on OrbStack.
  • Fast CLI Turnaround: Running a full container lifecycle through the standard docker CLI completes in 14.2 milliseconds on Kiri, outperforming competing runtimes by an order of magnitude.
  • Minimal Memory Footprint: Across a ten-container workload on Apple Silicon, Kiri consumes roughly 420 MB of RAM and 0.4% CPU, whereas OrbStack requires 1.1 GB and Docker Desktop consumes 2.5 GB.
  • Intelligent Auto-Sleep: After 60 seconds of inactivity, Kiri automatically puts its virtual machine to sleep, reducing the resident host daemon footprint to approximately 15 MB and waking in 0.15 seconds on the next request.

Under the Hood: How Kiri Achieves Sub-Millisecond Overhead

Kiri achieves its speed and density through a streamlined systems architecture tailored to each host operating system while sharing a unified Rust core.

Custom Minimal Kernel and Rust Guest Agent

On macOS, Kiri manages a single Linux virtual machine through Apple’s native Virtualization.framework using Rust bindings. Cold booting this virtual machine to a ready state takes just 112 milliseconds—down from 810 milliseconds on a standard stock kernel.

Inside the virtual machine runs a custom 10 MB Linux kernel compiled from allnoconfig with targeted patches for microsecond virtio-pci resets, Generic Segmentation Offload (GSO) for large TCP transfers, and proper FUSE file permissions. Acting as PID 1 is kiri-init, a static Rust binary weighing roughly 900 KB.

Instead of invoking runc or dockerd, this single-process agent uses one poll() loop to communicate with the macOS host over vsock with a median round-trip latency of 31 microseconds. When creating a container, kiri-init executes a single clone3 system call (CLONE_INTO_CGROUP) directly into new namespaces and cgroups, mounts overlayfs layers over an ext4 virtual disk, applies pivot_root, and configures networking via raw rtnetlink and nf_tables messages.

Native Linux Execution and Windows WSL 2 Bridge

On Linux hosts, Kiri bypasses virtualization entirely. The daemon runs directly on the host kernel using cgroup v2, spawning isolated processes via clone3 with zero virtual machine overhead.

On Windows 10 and Windows 11 (both x86-64 and ARM64), Kiri runs its Linux engine inside a WSL 2 distribution while kiri-win.exe exposes the Docker API on a Windows named pipe (npipe:////./pipe/kiri). Rather than relying on WSL’s localhost TCP relay—which frequently drops half-closed connections—Kiri bridges traffic directly over a single WSL stream without altering host firewall or network settings.

Core Features Beyond Standard Container Management

While raw execution speed is Kiri’s foundation, the runtime bundles essential developer tooling that typically requires third-party utilities or paid subscriptions.

Automatic Local Domains and Zero-Config HTTPS

Remembering randomized local port mappings across dozens of microservices slows down development. Kiri includes a built-in DNS resolver and reverse proxy that assigns readable domain names to every running container:

  • Zero-Setup Localhost Routing: Every container is immediately reachable by name at http://<name>.kiri.localhost without modifying system network settings.
  • Custom Local Top-Level Domains: Enabling local domain integration allows containers to resolve at http://<name>.kiri.local, while Compose stacks automatically answer at <service>.<project>.kiri.local.
  • Built-In Certificate Authority: Kiri generates a dedicated Certificate Authority stored in ~/.kiri/tls strictly scoped by name constraints to *.kiri.local and *.kiri.localhost, providing automatic HTTPS encryption for local web development.

Built-In Public Tunneling with Kiri Share

Testing third-party webhooks, demonstrating work-in-progress branches to clients, or previewing mobile web applications usually requires configuring external tools like Ngrok or Cloudflare Tunnels. Kiri includes a native public tunneling service called Kiri Share.

By clicking the Share button in the native desktop window or running kiri share <container-or-port> in the terminal, Kiri exposes your local service to the internet over HTTPS at https://<name>.runkiri.cloud. You can reserve persistent subdomains across machines, view active shares across all your computers, and immediately cut off public access the moment you disconnect or stop the runtime.

Single-Command Kubernetes, Linux Machines, and USB Passthrough

For cloud-native workflows and hardware engineering, Kiri extends well beyond basic OCI containers:

  • Instant Kubernetes Clusters: Running kiri k8s start provisions a single-node k3s cluster inside Kiri in approximately 20 seconds, automatically registering the kiri context in kubectl and exposing LoadBalancer services on localhost.
  • Full Linux Virtual Machines: With kiri machine create, you can launch persistent Ubuntu or systemd-enabled Linux environments with automatic user mapping, sudo privileges, and transparent host directory mounts.
  • USB Hardware Passthrough: Kiri allows developers on macOS, Windows, and Linux to pass physical USB devices—such as serial adapters, Zigbee sticks, and embedded microcontroller boards—directly into containers, automatically reattaching devices after macOS wakes from sleep.
  • Native Desktop Interface and Finder Integration: Built with native AppKit on macOS and Win32 on Windows rather than bloated Electron wrappers, Kiri’s interface supports 38 languages and mounts container filesystems read-only at ~/Kiri in macOS Finder.

Step-by-Step Guide to Installing Kiri

Setting up Kiri takes less than two minutes across all major desktop and server operating systems.

Installing on macOS, Windows, and Linux

  1. macOS (macOS 14+ on Apple Silicon or Intel): Download Kiri-<version>-arm64.dmg (or -x86_64.dmg for Intel Macs) from the official releases page. Drag Kiri.app into your Applications folder and launch it. Kiri bundles docker, docker-compose, and buildx, or you can choose the Kiri-Lite image if you already have the Docker CLI installed.
  2. Windows (Windows 10 and 11 with WSL 2): Download and run the Kiri-<version>-x86_64.msi or -arm64.msi per-user installer. Kiri automatically configures its WSL 2 environment and registers the named pipe context.
  3. Linux (Ubuntu, Fedora, Debian, RHEL): Download the .deb or .rpm package for your architecture (amd64 or arm64). Choose the standard kiri package to install the runtime alongside the Docker CLI tools, or kiri-lite for the standalone engine, then add your user to the kiri group.

Building Kiri from Source with Rust

Developers who prefer compiling from source only need a working Rust toolchain and an existing container engine to build the initial kernel template:

git clone https://github.com/libracoder/kiri.git
cd kiri

# Build the custom 10 MB Linux kernel and 64 GiB sparse ext4 disk template
cargo xtask kernel
cargo xtask disk

# Build the static Rust PID 1 guest agent and signed host binary
cargo xtask guest
cargo xtask host

# Start the Kiri daemon and register the Docker context
./target/release/kiri daemon &
docker context create kiri --docker host=unix://$HOME/.kiri/run/docker.sock

Migrating from Docker Desktop or OrbStack

You do not need to rebuild images or recreate databases from scratch when switching runtimes. Open your terminal and run the built-in migration command:

kiri import

This command inspects your existing Docker Desktop or OrbStack storage and migrates your local images, named volumes, and container states directly into Kiri.

Practical Workflows: How to Use Kiri for Daily Development

Once Kiri is running, it automatically configures the kiri Docker context. You can invoke standard docker commands or use the kiri CLI wrapper, which always targets the Kiri engine regardless of your active context.

Running Containers and Docker Compose Stacks

Launch isolated containers or multi-service Compose applications using familiar syntax:

# Run a quick disposable Alpine container
kiri run --rm alpine echo "Hello from Kiri"

# Start a detached Nginx web server named 'web'
kiri run -d --name web -p 8080:80 nginx:alpine

# Reach the container immediately via zero-config local DNS
curl http://web.kiri.localhost

# Launch a multi-container Docker Compose project
kiri compose up -d

Exposing Local Services and Testing Webhooks

To share your running web container with an external webhook provider or remote teammate over HTTPS, run:

# Expose a container by name or local port number
kiri share web
# Or share a specific local port directly
kiri share 8080

Kiri immediately outputs a live [https://web.runkiri.cloud](https://web.runkiri.cloud) URL backed by automatic TLS termination.

Launching Local Kubernetes Clusters and Ubuntu Sandboxes

When your workflow requires testing Kubernetes manifests or compiling software inside a full Linux userland, Kiri handles both with single commands:

# Start a single-node k3s cluster and verify nodes
kiri k8s start
kubectl --context kiri get nodes

# Create an Ubuntu development machine and open an interactive shell
kiri machine create dev --distro ubuntu
kiri machine shell dev

Tuning Virtual Machine CPU and Memory Limits

While Kiri dynamically returns unused memory to the host via virtio ballooning, you can explicitly cap virtual machine resources via the graphical Settings menu, by editing ~/.kiri/vm.json, or by exporting environment variables before starting the daemon:

export KIRI_CPUS=4
export KIRI_MEMORY_MIB=8192

Frequently Asked Questions (FAQ)

Does Kiri require replacing existing Dockerfiles or Compose configurations?

No. Kiri implements the standard Docker Engine API and uses BuildKit for image builds, meaning all existing Dockerfile definitions, docker-compose.yml files, and CI/CD scripts run without changes.

Can Kiri run x86_64 images on Apple Silicon Macs?

Yes. Kiri shares macOS Rosetta into the Linux guest virtual machine over virtiofs and registers it with binfmt_misc, allowing linux/amd64 container images and BuildKit steps to execute transparently at near-native speeds on Apple Silicon.

How does Kiri handle security and container isolation?

Kiri enforces Docker’s default Linux capabilities, applies a strict default seccomp system call filter, and supports --cap-drop, --read-only, and no-new-privileges. Even when running --privileged containers, Kiri protects the host boundary by blocking container access to vsock sockets and io_uring.

You may also like

Subscribe
Notify of
guest

0 Comments
Newest
Oldest Most Voted