Lima: Linux VMs with shared folders and forwarded ports

Lima: Linux VMs with shared folders and forwarded ports

Introduction

Lima runs Linux virtual machines with automatic directory sharing and port forwarding so you edit on the host and build or run workloads in the guest—roughly in the spirit of Microsoft’s narrative for WSL2, but centered on QEMU or Apple’s Virtualization.framework rather than embedding Windows internals. The upstream docs describe Lima as aiming (originally) to bring containerd and nerdctl to Mac users, while still supporting arbitrary Linux commands and other engines (Docker, Kubernetes, Podman, and more are covered in docs and adopters lists on the main repository README).

If you already think in terms of “where does the kernel boundary go for an AI or team devbox?”, our earlier framing of OCI + Lima + heavier isolation maps Lima onto the desktop Linux VM rung of that ladder. A worked example of that pattern—golden image plus short-lived clones, agent-friendly SSH, and per-create secret injection—is dev-ore devbox. This post drills into what Lima guarantees, which hypervisor backs your instance, and how templates line up with day-to-day container workflows.

What you get before talking about YAML

Installing from Homebrew is what the Lima README documents first (brew install lima), followed by limactl start for a default instance and lima uname -a to execute commands inside the VM (getting started snippet). Under the hood, each instance is a VM with Lima handling guest boot, filesystem mounts, networked port exposure toward the host, and lifecycle commands via limactl.

Upstream positions Lima as complementary to sshocker, another project in the lima-vm org that emphasizes SSH with file sharing and port forwarding, which captures how Lima exposes much of its ergonomics despite not being “just SSH” anymore (docs home).

Governance-wise, Lima joined the CNCF as a Sandbox project in September 2022; Lima’s docs record a move to the Incubating level in October 2025 (the CNCF announcement was November 11, 2025) (Lima docs home, CNCF blog).

Picking vmType: QEMU, VZ, WSL2, and why it freezes at creation

Lima abstracts over several virtual machine drivers; vmType is chosen when the instance is created and cannot be changed afterward (VM types docs). That constraint matters when you bootstrap the wrong driver for emulation needs on Apple Silicon—you would create a fresh instance rather than flipping a toggle.

Rough decision flow from the documented flowchart (same page):

  • Windows hosts use the WSL2 backend in that matrix.
  • Linux hosts default to QEMU (recommended releases are called out separately for Linux vs macOS in the QEMU page (QEMU docs)).
  • macOS hosts steer toward vz, Apple’s Virtualization.framework driver, unless you deliberately need behaviours that mandate QEMU—including running a full Intel guest on ARM or the reverse, where the docs funnel you toward QEMU for slower full-system emulation versus faster userspace-centric setups (diagram on VM types).

Lima prior to v1.0 defaulted new instances to QEMU. From Lima v1.0 onward, vz is the default vmType for new instances on macOS 13.5 or later, unless the config is incompatible with VZ (the vmType page calls out specifying a non-native guest architecture; it also states QEMU was the default before v1.0). That is separate from using VZ at all: the VZ driver docs list macOS 13 or later and Lima 0.14 or later. The vmType page’s “last modified” footer (currently March 15, 2026) links the commit that defaults non-native architectures to QEMU.

Operational takeaway: verify limactl list (or inspect the instance YAML) when debugging performance or mount oddities—you may be comparing Intel userspace emulation versus running an entire Intel guest, not “two identical Lima setups.”

Container workflows the README emphasizes

The README treats container workflows alongside a basic shell: lima uname -a proves the guest kernel, while lima nerdctl … exercises containerd directly. For Docker compatibility, the README steers you through limactl start template:docker, setting DOCKER_HOST from limactl list, and then running docker on the host against the guest daemon (README). For Kubernetes, limactl start template:k8s is the entry point, with follow-on kubectl usage described in the same block—check the current template because kubeconfig paths and helper commands evolve per release.

If you only need containerd + nerdctl, the stock quick start is literally:

Copy
lima nerdctl run --rm hello-world

That keeps the mental model honest: nerdctl is the containerd-native CLI, and Lima is what makes that Linux stack feel local on a Mac.

How Lima shows up in other products

The README’s Adopters section is the low-risk way to place Lima in the ecosystem without speculating: Rancher Desktop, Colima, Finch, and Podman Desktop (with a Lima plug-in) all point at Lima-class machinery for desktop container workflows (README list). That means choosing “Colima” vs raw Lima is often a UX and default template question, not a different hypervisor category—still a Linux VM with shared storage and ports unless the wrapper changes the graph.

Multi-arch and non-Linux guests (where expectations bend)

The docs home still advertises Intel-on-Intel, ARM-on-ARM, ARM-on-Intel, Intel-on-ARM (with a dedicated multi-arch configuration page), and experimental guests such as macOS and FreeBSD (docs home). Treat those last categories as capability flags that may trade away polish compared to the well-trodden Linux templates.

When Lima is the wrong tool

Lima optimizes for one or a few long-lived local VMs with tight host integration. It is not a drop-in replacement for remote CI runners, multi-tenant isolation, or nested production Kubernetes—those problems usually want different scheduling, storage, and guardrails. Firecracker-style microVMs and the Lima vs Firecracker comparison spell out why. On macOS, you should also budget RAM, disk images, and boot latency against the convenience of a real Linux kernel and daemons.

Conclusion

Lima is best understood as a Linux VM manager with first-class dev ergonomics (shared directories, forwarded ports, templates) and deep roots in containerd/nerdctl, now CNCF Incubating (docs home). Choose vmType deliberately at instance creation—VZ vs QEMU on macOS is the big fork—then lean on templates for Docker or Kubernetes when you do not want to hand-roll cloud-init and mounts. For how that fits into broader isolation choices (OCI contracts, LXC, microVMs), keep the devbox ladder post handy. When collaborators ask whether Lima is “like Firecracker,” send them to Lima VMs vs Firecracker microVMs rather than debating slogans.

If you aim agents into Lima’s guest for kernel separation, skim Pi and Terax—same agents, opposite terminal philosophies—plus schema-first secrets if copied env files are the weak link.

Featured Posts