DOCSEARCHbyAlgolia
Submit Docs

Lima

repository·master·Indexed 12 days ago

https://github.com/lima-vm/lima

A tool for launching Linux virtual machines on macOS and other hosts with automatic file sharing and port forwarding. Lima provides a WSL2-like experience and is primarily used to run container engines such as containerd (via nerdctl), Docker, Podman, and Kubernetes. It includes a variety of templates for different Linux distributions and provides wrapper scripts for docker, kubectl, and apptainer.

Tokens
60.4K
Snippets
241
Records
322
Agent score
97%

What's inside Lima

  1. Overview of Lima features

    master

    Lima is a tool for launching Linux virtual machines with features similar to WSL2. It provides automatic file sharing and automatic port forwarding between the host and the guest.

    Key capabilities include:

    • Container Support: Built-in support for containerd (and other container engines).
    • Architecture Support: Supports Intel on Intel, ARM on ARM, and cross-architecture scenarios like ARM on Intel or Intel on ARM.
    • Guest Distributions: Supports various Linux distributions including Ubuntu (default), Debian, Fedora, Arch Linux, Alpine, AlmaLinux, openSUSE, Oracle Linux, and Rocky Linux.
    • Experimental Non-Linux Guests: Experimental support is available for macOS, FreeBSD, and Windows guests.

  2. Explore projects and tools using Lima

    master

    Lima is used as a foundation for several container environments and GUI tools:

    Container Environments

    • Rancher Desktop: Kubernetes and container management for the desktop.
    • Colima: Minimal setup for Docker and Kubernetes on macOS.
    • Finch: A command line client for local container development.
    • Podman Desktop: Includes a plugin specifically for Lima virtual machines.

    GUI Tools

    • Lima xbar plugin: An xbar plugin to manage VM status (start/stop/running) from the macOS menu bar.
    • lima-gui: A Qt-based graphical user interface for Lima.

  4. Explore Lima subprojects

    master

    Several components of Lima are maintained in separate repositories. Depending on your needs, you may want to use these specialized subprojects:

    • socket_vmnet: Provides vmnet.framework support for unmodified rootless QEMU.
    • lima-actions: Enables running Lima within GitHub Actions environments.
    • go-qcow2reader: A Go implementation of a qcow2 reader.
    • sshocker: A tool providing SSH, reverse SSHFS, and port forwarding via a Docker-like CLI (the predecessor to Lima).
    • alpine-lima: Used to create Alpine Linux-based images for Lima.

    You can find a full list of subprojects at https://github.com/lima-vm.

  5. Configure filesystem mounts in Lima

    master

    Lima provides several methods to mount host directories into the guest VM. The default mount type depends on your Lima version and host OS:

    Lima VersionDefault Mount Type
    < 0.10reverse-sshfs + Builtin SFTP server
    >= 0.10reverse-sshfs + OpenSSH SFTP server
    >= 0.17reverse-sshfs + OpenSSH SFTP server (QEMU) or virtiofs (VZ)
    >= 1.09p (QEMU, non-Windows) or virtiofs (VZ)

    To disable all filesystem mounts, use plain mode.

  6. What is the Krunkit VM type?

    master
    Krunkit is an experimental VM type for Lima that runs super-lightweight VMs on macOS/ARM64 (Apple Silicon) with a primary focus on high-performance GPU access. It leverages libkrun to embed a VMM that uses HVF on macOS. Its standout feature is enabling Vulkan workloads inside the guest VM via Mesa's Venus Vulkan driver, making it ideal for running AI models and GPU-accelerated workloads.

  8. Compare Lima and Colima for container runtimes

    master

    Colima is a third-party project that wraps Lima to provide an alternative user experience for launching containers. The primary difference is their default container runtime: Lima defaults to containerd, whereas Colima defaults to Docker.

    Use the following command mappings to achieve specific runtimes:

    ContainerLima CommandColima Command
    containerdlimactl startcolima start --runtime=containerd
    Dockerlimactl start template:dockercolima start
    Podmanlimactl start template:podmanNot supported
    Kubernetes (k3s)limactl start template:k3scolima start --kubernetes
    Kubernetes (kubeadm)limactl start template:k8sNot supported
    # Lima default (containerd)
limactl start

# Colima default (Docker)
colima start

  9. How URL handler plugins work in Lima

    master

    Lima's template locator supports custom URL schemes via plugins. A plugin named limactl-url-<scheme> handles URLs starting with <scheme>:.

    When Lima encounters an unrecognized scheme (e.g., dev:webapp):

    1. It searches for an executable named limactl-url-dev in your PATH using the standard plugin discovery mechanism.
    2. It calls the plugin with the part after the colon as the sole argument (e.g., webapp).
    3. It reads the plugin's stdout, which must be either a URL (with any supported scheme) or a local file path.

    Key Behaviors:

    • Chaining: The plugin's output can itself use a custom scheme. Lima resolves the chain until it reaches a final https: URL or local file path. It detects and rejects redirect loops.
    • Error Handling: If the plugin exits with a non-zero status, Lima reports the error. Any stderr output from the plugin is included in the error message.
    • Testing: You can preview what a custom URL resolves to without fetching the template using limactl template url.

    Warning: Support for URL handler plugins is experimental. Requires Lima >= 2.0.

    $ limactl template url dev:webapp
https://github.example.com/raw/infra/lima-templates/master/webapp.yaml

  10. macOS guest limitations and caveats

    master

    macOS guests in Lima have several differences and limitations compared to Linux guests:

    Authentication and Sudo

    • Password login: Enabled.
    • Sudo: Password-less sudo is disabled, with the sole exception of /sbin/shutdown -h now. This behavior is currently not configurable.

    Feature Limitations

    • Video: No support for turning off the video display.
    • Networking: Automatic port forwarding is not supported. To access services on the guest, you must either:
      • Use ssh -L to manually set up port forwarding.
      • Use the vzNAT network to access the guest via its IP address.
    • Certificates: No support for installing custom caCerts.
    • Containerization: containerd is not available.

    Plain Mode

    Because containerd and automatic port forwarding are unavailable on macOS guests by default, using plain mode on macOS only serves to disable host directory mounts.

  12. Understand what still works in Plain mode

    master

    Even in Plain mode, certain core Lima functionalities remain active:

    • Static port forwarding: portForwards rules with static: true are still established.
    • Provisioning scripts: User, system, and data provisioning scripts are still executed.
    • Base guest setup: The base user and SSH keys are still configured.