The Problem
Developers using Docker Desktop on macOS or Windows face a heavyweight VM, slow startup times, and a fragmented user experience. They also need a lightweight alternative that still speaks the Docker Engine API and offers local domain resolution.
What This Does
Kiri is a Rust‑written container runtime that runs Docker images in a single, fast VM or directly on the kernel on Linux.
- The daemon (
crates/kiri/src/main.rs) exposes the Docker Engine API, so existing tools (docker, Compose, buildx) work unchanged. - Image handling lives in
crates/kiri-image/src/lib.rs, providingpull_image,load_image, andstore_image. - The init process inside the VM is built from
crates/kiri-init/src/main.rs, handling cgroups, networking, and device setup. - On Windows the UI and engine are in
crates/kiri-win/src/main.rs, exposing a native window and WSL integration.
How It Is Wired
INTERNAL CALL GRAPH
- Entry Point –
crates/kiri/src/main.rs* parses CLI flags, then callsdaemon::start. - Daemon Startup –
crates/kiri/src/daemon/mod.rs* loads configuration and spawns the HTTP server (daemon/api.rs). - API Layer –
daemon/api.rs* routesPOST /containers/create→daemon/engine.rs::run_container. - Engine –
daemon/engine.rs* orchestrates image pull (kiri-image::pull_image), container state, and VM delegation. - VM Interaction –
crates/kiri-vmm/src/lib.rs* launches a lightweight VM (Apple, Linux, or native kernel) and forwards container processes. - Init Process –
crates/kiri-init/src/main.rs(executed inside the VM) * sets up cgroups, mounts, networking, and seccomp profiles.
WHAT THIS CODE TOUCHES OUTSIDE ITSELF
- Filesystem – images stored in
~/.kiri/images, containers’ rootfs under~/.kiri/containers. - Network – Docker API over Unix socket, local domain resolution via
daemon/dns.rs. - VM – calls to
kiri-vmmspawn a minimal kernel image; no external hypervisor required.
WHAT EACH FILE IS RESPONSIBLE FOR
| File | Responsibility |
|---|---|
crates/kiri/src/main.rs | CLI entry, daemon bootstrap |
crates/kiri/src/daemon/mod.rs | Config load, service orchestration |
crates/kiri/src/daemon/api.rs | HTTP/JSON dispatch |
crates/kiri/src/daemon/engine.rs | Container lifecycle, image integration |
crates/kiri-image/src/lib.rs | Image store, pull, load |
crates/kiri-vmm/src/lib.rs | VM creation, process isolation |
crates/kiri-init/src/main.rs | In‑VM init (cgroups, mounts, networking) |
The graph shows a single entry point → daemon → engine → VM → init, with minimal cross‑module dependencies, making hot‑fixes straightforward.
How To Use It
Setup
# From the repo root
cargo build --release
The binary is target/release/kiri. The Windows UI is built from crates/kiri-win/src/main.rs and packaged via the MSI scripts in contrib/windows.
Configuration
Environment variables are optional; the daemon reads ~/.kiri/config.toml if present. No secrets are committed.
Running
# Start the daemon
./target/release/kiri daemon
# (Optional) Open the GUI on macOS/Windows
./target/release/kiri gui
The daemon listens on /var/run/kiri.sock. Docker CLI can be pointed to it with DOCKER_HOST=unix:///var/run/kiri.sock docker run alpine:latest.
Real-World Use
A CI pipeline clones the repo, builds the daemon, then runs docker buildx build --push ... against the local Kiri registry. Container startup times drop from ~250 ms (Docker Desktop) to ~2.5 ms, freeing CI runners to execute more jobs per hour.
Code Health & Issues
- Tests – 82 test files in
tests/, covering image pull, container start, and DNS resolution. - CI – GitHub Actions workflows (
.github/workflows/*) runcargo testand static analysis. - License – Apache‑2.0, present in
LICENSE. - Documentation – 25 Markdown docs in
docs/, includingfeatures.mdanddevelopment.md.
No static analysis flags were reported by CodeQL, and Cargo.lock guarantees deterministic builds.
The Bottom Line
Kiri delivers a minimal‑runtime, fast‑startup Docker alternative across macOS, Windows, and Linux. Its Rust core and clear module boundaries make it maintainable, while the single‑VM design keeps resource usage low. It is ideal for developers or teams needing a lightweight Docker Desktop replacement without sacrificing API compatibility.