Overview

Relevant source files

Purpose and Scope

This page provides a high-level introduction to the Lima project, its architecture, and core components. Lima (Linux Machines) is a system for launching and managing Linux virtual machines on non-Linux hosts (macOS, Windows, Linux) with automatic file sharing, port forwarding, and container runtime integration.

For installation and usage instructions, see Getting Started. For detailed architecture information about specific subsystems, see Architecture Overview. For the configuration system details, see Configuration System.

What is Lima?

Lima launches Linux virtual machines with features similar to WSL2, providing:

Automatic file sharing between host and guest through multiple mount protocols
Automatic port forwarding for seamless network access to guest services
Container runtime integration supporting containerd, Docker, Podman, and Kubernetes
Cross-platform virtualization using QEMU, Apple Virtualization Framework (VZ), or WSL2
Template-based provisioning for quick deployment of pre-configured environments

Lima was originally created to promote containerd and nerdctl to macOS users, but has evolved into a general-purpose Linux VM manager that works across macOS, Linux, Windows, and even NetBSD.

Sources: README.md1-22 go.mod1-148

Core Architecture

High-Level System Components

Sources: go.mod1-148 Diagram 1 from context

Primary Code Modules

Module	Package Path	Purpose
limactl	`cmd/limactl`	Main CLI entry point, command parsing and execution
lima-guestagent	`cmd/lima-guestagent`	Guest-side daemon for status reporting and coordination
hostagent	`pkg/hostagent`	Host-side daemon managing VM lifecycle and guest communication
limayaml	`pkg/limayaml`	YAML configuration loading, validation, and merging
driver	`pkg/driver`	VM driver abstraction layer (interface and implementations)
qemu	`pkg/driver/qemu`	QEMU virtualization driver for Linux/macOS
vz	`pkg/vz`	Apple Virtualization.framework driver for macOS
wsl2	`pkg/wsl2`	WSL2 driver for Windows
cidata	`pkg/cidata`	Cloud-init ISO generation and provisioning scripts
networks	`pkg/networks`	Network configuration and daemon management
downloader	`pkg/downloader`	Image download and caching system
sshutil	`pkg/sshutil`	SSH connection management and utilities
store	`pkg/store`	Instance storage and directory layout management

Sources: go.mod1-148

Platform and Dependency Matrix

Supported Platforms

Lima runs on multiple platforms with different virtualization backends:

Host OS	Virtualization Backend	Status
macOS (Intel)	QEMU	Stable
macOS (Intel)	VZ (Virtualization.framework)	Stable
macOS (Apple Silicon)	QEMU	Stable
macOS (Apple Silicon)	VZ (Virtualization.framework)	Stable (Recommended)
Linux	QEMU	Stable
Windows	WSL2	Stable
NetBSD	QEMU	Experimental

Sources: README.md21 go.mod9-10

Key Dependencies

Sources: go.mod6-58

Project Structure

Source Code Organization

Sources: Project repository structure observation

Configuration Files

File	Purpose
`go.mod`	Main Go module dependencies
`hack/tools/go.mod`	Development tool dependencies (golangci-lint, protolint, shfmt)
`.github/dependabot.yml`	Automated dependency updates configuration
`Makefile`	Build orchestration and cross-compilation
`templates/*.yaml`	Built-in instance templates (default, docker, k8s, etc.)

Sources: go.mod1-4 hack/tools/go.mod1-22 .github/dependabot.yml1-22

Key Features

Instance Lifecycle Management

Lima manages VM instances through a well-defined lifecycle with persistent state stored in ~/.lima/INSTANCE_NAME/. Each instance transitions through these states:

Creating: Configuration validation, image download, disk preparation
Stopped: VM powered off but configuration and disks preserved
Starting: VM boot, agent startup, network setup, mount initialization
Running: Full operation with all features active
Broken: Recoverable error state with partial functionality

The CLI provides commands to manage these transitions: create, start, stop, delete, restart, clone, and rename.

Sources: Diagram 2 from context

Multi-Protocol Communication

Lima uses multiple communication channels between host and guest:

Protocol	Transport	Purpose
SSH	TCP over network	Primary channel for shell access, file operations, and port forwarding
gRPC	VSOCK/VirtIO or serial	High-performance bidirectional communication for status and events
HTTP	Unix socket	Simple query interface for instance information

Sources: Diagram 3 from context, go.mod47-51

Automatic Resource Management

File Sharing: Reverse SSHFS, VirtioFS, 9P, or native WSL mounts
Port Forwarding: Static (pre-configured) and dynamic (automatically discovered)
Network Modes: user-v2 (no sudo), shared (NAT via socket_vmnet), bridged (direct host network)
Storage: Copy-on-write disk images with caching to avoid duplicate downloads

Sources: Diagram 5 and 6 from context

Template System

Lima provides a template system for quick deployment of pre-configured environments:

Built-in templates: default, docker, k8s, podman, alpine, etc.
User can create custom templates
Template variables: {{.Home}}, {{.Param.*}}, etc.
Four-tier configuration priority: override > user > default > builtin

Usage example:

Sources: README.md40-52 Diagram 4 from context

Development and Build System

Build Dependencies

Lima uses a separated dependency model to keep production binaries clean:

Main module (go.mod): Runtime dependencies only
Tools module (hack/tools/go.mod): Development tools like golangci-lint, protoc-gen-go, shfmt

This separation prevents dev-time dependencies from being included in release artifacts.

Sources: go.mod1-4 hack/tools/go.mod1-22 hack/tools/pinversion.go1-18

Automated Dependency Management

Dependabot is configured to automatically update dependencies:

Daily updates for Go modules in both main and tools directories
Daily updates for GitHub Actions
Grouped updates for related packages (golang.org/x/*, k8s.io/*)

Sources: .github/dependabot.yml1-22

Multi-Architecture Support

Lima's build system produces:

Host binaries for macOS (Intel/ARM), Linux (amd64/arm64), Windows (amd64)
Guest agent binaries for multiple Linux architectures (amd64, arm64, riscv64, etc.)
Release archives bundling all necessary components

Sources: Diagram 6 from context

Community and Ecosystem

Lima is a CNCF incubating project and has been adopted by several prominent tools:

Rancher Desktop: Kubernetes and container management
Colima: Docker/Kubernetes on macOS with minimal setup
Finch: AWS's command line client for local container development
Podman Desktop: GUI with Lima VM plugin

Sources: README.md64-72 README.md91-96

Next Steps:

For installation and basic usage, see Getting Started
For detailed architecture, see Architecture Overview
For configuration details, see Configuration System
For CLI commands, see Command Line Interface