If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lima-vm/lima shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 13 active contributors
• Distributed ownership (top contributor 30% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lima-vm/lima repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lima-vm/lima.

What it runs against: a local clone of lima-vm/lima — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lima-vm/lima | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lima-vm/lima. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lima-vm/lima.git
#   cd lima
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lima-vm/lima and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lima-vm/lima(\\.git)?\\b" \\
  && ok "origin remote is lima-vm/lima" \\
  || miss "origin remote is not lima-vm/lima (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/limactl/main.go" \\
  && ok "cmd/limactl/main.go" \\
  || miss "missing critical file: cmd/limactl/main.go"
test -f "cmd/lima-guestagent/main.go" \\
  && ok "cmd/lima-guestagent/main.go" \\
  || miss "missing critical file: cmd/lima-guestagent/main.go"
test -f "cmd/lima-driver-qemu/main.go" \\
  && ok "cmd/lima-driver-qemu/main.go" \\
  || miss "missing critical file: cmd/lima-driver-qemu/main.go"
test -f "cmd/lima-driver-vz/main_darwin.go" \\
  && ok "cmd/lima-driver-vz/main_darwin.go" \\
  || miss "missing critical file: cmd/lima-driver-vz/main_darwin.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lima-vm/lima"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Lima launches lightweight Linux virtual machines on macOS, Linux, and NetBSD with automatic file sharing and port forwarding (similar to WSL2). Its core strength is seamless container integration—it ships with containerd and nerdctl by default but supports Docker, Podman, and Kubernetes. The original goal was to promote containerd to Mac users, but it's evolved into a general-purpose Linux VM launcher suitable for non-container workloads too. Monorepo with clear separation: cmd/lima is the main CLI entry point; cmd/lima-guestagent runs inside VMs to handle mounting and networking; cmd/lima-driver-* are hypervisor-specific backends (QEMU, Virtualization.framework on Darwin, Hyper-V on Windows). Go is dominant (~1.3M LOC) with shell scripts for build/test infrastructure. Templates in cmd/*.lima (docker.lima, kubernetes.lima) define pre-configured VM flavors.

Container developers and DevOps engineers on macOS who want to run Linux workloads (especially containers) without heavyweight VirtualBox/VMware overhead. Also used by projects like Rancher Desktop, Colima, and Finch that wrap Lima as their underlying VM engine. Contributors are maintainers focused on cross-platform VM/container tooling.

Production-ready and actively maintained. The codebase is substantial (~1.3M lines of Go, organized CI/CD in .github/workflows/, OpenSSF Best Practices badge, and regular release cadence). The project has established adopters (Rancher Desktop, Colima, Finch) and clear governance (MAINTAINERS.md), indicating stability. Active development with recent commits and issue triage.

Relatively low risk for a VM hypervisor tool. Dependencies are reasonable and mostly established (Code-Hex/vz for Virtualization.framework, qemu drivers, containers/gvisor-tap-vsock). The main risk is platform-specific fragmentation—the codebase maintains Darwin/Linux/Windows code paths (cmd/lima-driver-qemu, cmd/lima-driver-vz, cmd/lima-driver-wsl2), so changes risk breaking one platform. Single-maintainer risk is mitigated by MAINTAINERS.md listing multiple people.

Active development on hypervisor drivers (Virtualization.framework via Code-Hex/vz, krunkit driver), networking (gvisor-tap-vsock integration), and guest agent improvements. CI includes CodeQL scans, spell-check, and multi-platform testing (.github/workflows/test.yml). Recent additions: limactl-mcp (Model Context Protocol support) and improved template caching (.github/actions/setup_cache_for_template).

git clone https://github.com/lima-vm/lima.git
cd lima
make

For macOS via Homebrew: brew install lima && limactl start. For Linux/development, clone and make builds the Go binaries. Run tests with make test (see Makefile for test targets).

Daily commands: Development: make build compiles binaries to _output/bin/limactl and _output/bin/lima. To test a VM: _output/bin/limactl start (creates ~/.lima/default/lima.yaml). For guest agent: make -C cmd/lima-guestagent build and install via install_systemd_linux.go logic. See Makefile for full targets (make test, make lint, make release).

• cmd/limactl/main.go — Main entry point for the Lima CLI—all user commands route through here; essential for understanding command structure and initialization.
• cmd/lima-guestagent/main.go — Guest agent that runs inside the Linux VM, handling mounts, port forwarding, and container runtime integration—core to Lima's host-guest communication.
• cmd/lima-driver-qemu/main.go — QEMU hypervisor driver; primary Linux VM backend on non-Darwin systems and the default cross-platform virtualization strategy.
• cmd/lima-driver-vz/main_darwin.go — Virtualization framework (VZ) driver for macOS ARM64; native alternative to QEMU on Apple Silicon, critical for M-series performance.
• go.mod — Go module definition listing all dependencies; essential for understanding external libraries, especially gvisor-tap-vsock and containerd integrations.
• Makefile — Build, test, and release orchestration; defines how the project compiles and validates binaries for multiple platforms.
• .github/workflows/test.yml — Primary CI/CD pipeline; shows how Lima tests are run across platforms and where regressions are caught.

Add a new VM template (e.g., for a container runtime)

1. Create a new template file in cmd/ directory following naming convention (e.g., cmd/newruntime.lima) (cmd/newruntime.lima)
2. Define the VM image URL, provisioning script, and enabled services using YAML (see cmd/docker.lima or cmd/podman.lima as reference) (cmd/newruntime.lima)
3. Update cmd/limactl/template.go to register the new template in the template list (cmd/limactl/template.go)
4. Run code generation to update documentation and schema files (Makefile)

Add a new CLI command (e.g., limactl snapshot)

1. Create cmd/limactl/yourcommand.go implementing a cobra.Command struct with Run callback (cmd/limactl/yourcommand.go)
2. Register the command in cmd/limactl/main.go by calling rootCmd.AddCommand(yourCommand) in init() (cmd/limactl/main.go)
3. Implement host-side logic in cmd/limactl and guest operations in cmd/lima-guestagent/ if needed (cmd/limactl/yourcommand.go)
4. Add integration tests in cmd/limactl/yourcommand_test.go or .github/workflows/test.yml for CI coverage (.github/workflows/test.yml)

Add hypervisor driver support for a new platform

1. Create cmd/lima-driver-yourplatform/main_yourplatform.go implementing driver initialization and VM lifecycle hooks (cmd/lima-driver-yourplatform/main_yourplatform.go)
2. Implement VM startup, shutdown, and device attachment via the driver's entry point (cmd/lima-driver-yourplatform/main_yourplatform.go)
3. Wire driver selection in cmd/limactl/main_yourplatform.go to auto-select your driver on target OS/arch (cmd/limactl/main_yourplatform.go)
4. Add CI job in .github/workflows/test.yml for platform-specific testing and build artifact generation (.github/workflows/test.yml)

Extend guest agent functionality (e.g., new mount type or service)

1. Add handler logic to cmd/lima-guestagent/main.go or create a new module in that directory (cmd/lima-guestagent/main.go)
2. For Linux-specific code, add implementation in cmd/lima-guestagent/daemon_linux.go or root_linux.go (cmd/lima-guestagent/daemon_linux.go)
3. Update cmd/lima-guestagent/install_systemd_linux.go to install systemd units if your feature requires persistent services (cmd/lima-guestagent/install_systemd_linux.go)
4. Test by rebuilding the guest agent binary and validating with lima start; add to test.yml CI for regression detection (.github/workflows/test.yml)

• Go — Fast compilation, single cross-platform binary, excellent standard library for systems programming and networking; minimal dependencies align with Lima's goal of lean container tooling.
• QEMU — Mature, widely-supported hypervisor; runs on Linux, macOS Intel, and other platforms. Default choice for cross-architecture VM execution.
• Virtualization.framework (VZ) — Native Apple Silicon (M1/M2/M3) hypervisor on macOS; delivers near-native performance vs. QEMU emulation, critical for M-series adoption.
• gvisor-tap-vsock — User-mode networking without root; enables port forwarding and container connectivity without privilege escalation on host.
• systemd — Standard service manager on modern Linux

Platform-specific code paths: Darwin, Linux, Windows, and NetBSD each have conditional builds (see main_darwin.go, main_windows.go patterns). Tests may pass on one OS but fail on another—use GOOS=linux make test to target specific OSes. Guest agent coupling: changes to lima-guestagent must be compatible with older VMs (backwards compatibility matters since VMs persist). SSH tunnel dependency: everything tunnels over SSH—if SSH config is broken, the entire CLI hangs (check ~/.lima/default/ssh.config). Systemd vs init: guest agent installation logic differs (install_systemd_linux.go vs root_others.go)—test on both. Hardware acceleration: Virtualization.framework (vz) requires Apple Silicon or Intel with nested virtualization enabled; QEMU is the fallback but slower.

• Virtual socket (vsock) — Lima uses vsock (from gvisor-tap-vsock) to tunnel network traffic between host and guest without traditional TAP interfaces; understanding vsock is essential for debugging networking issues
• SSH tunneling for RPC — The entire host-guest communication happens over SSH (see lima-guestagent listening on SSH); changes to SSH setup or command dispatch affect all VM operations
• Hypervisor abstraction (driver pattern) — Lima supports multiple hypervisors (QEMU, Virtualization.framework, Hyper-V) via pluggable drivers in cmd/lima-driver-*/; adding new hypervisor support requires implementing the driver interface
• QCOW2 (QEMU Copy-On-Write 2) — Lima uses go-qcow2reader to manage QEMU disk images efficiently; understanding QCOW2 is important for debugging storage issues or optimizing disk layout
• Systemd socket activation and user services — Guest agent uses systemd socket activation (lima-guestagent.TEMPLATE.service) for reliable guest daemon startup; changes to service files affect VM initialization
• Transparent proxy and NAT — gvisor-tap-vsock implements transparent TCP/UDP proxying so host ports appear to be listening locally even though the service runs in the guest; critical for port forwarding UX
• Cloud-init (guest initialization) — Lima VMs can be provisioned via cloud-init (fake_cloud_init_darwin.go); understanding cloud-init is needed to customize VM initialization scripts and dependencies

• containerd/nerdctl — Recommended container runtime for Lima; lima ships with nerdctl by default for rootless container execution
• rancherdesktop/rancherdesktop — Major adopter that uses Lima as its underlying VM engine to run Kubernetes and container management on macOS/Windows
• abiosoft/colima — Popular wrapper around Lima that simplifies Docker (and Kubernetes) setup on macOS with minimal configuration
• microsoft/WSL — Spiritual predecessor and inspiration; Lima's file sharing and port forwarding design mirrors WSL2's seamless integration
• containers/gvisor-tap-vsock — Critical dependency for Lima's networking stack; provides transparent TCP/UDP port forwarding between host and guest

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for limactl subcommands (clone, copy, disk, edit)

The cmd/limactl directory contains multiple subcommands (clone.go, copy.go, disk.go, edit.go, etc.) but there are no visible integration tests. The existing editflags_test.go only tests flag parsing. New contributors could add end-to-end tests for common workflows like cloning VMs, copying files, and managing disks, which would improve reliability and serve as documentation.

• [ ] Create pkg/testing/integration or similar test utilities package for VM lifecycle testing
• [ ] Add integration tests for limactl clone command (cmd/limactl/clone.go) verifying VM configuration is properly copied
• [ ] Add integration tests for limactl copy command (cmd/limactl/copy.go) testing file transfer to/from VMs
• [ ] Add integration tests for limactl disk command (cmd/limactl/disk.go) testing disk resize operations
• [ ] Integrate tests into .github/workflows/test.yml if not already present

Add unit tests for hostagent networking and port forwarding logic

The repo includes multiple network-related drivers (cmd/lima-driver-qemu, cmd/lima-driver-vz, cmd/lima-driver-wsl2) and dependencies like inetaf/tcpproxy and containers/gvisor-tap-vsock, suggesting complex networking logic. However, there are no visible tests for port forwarding, network translation, or vsock communication. This is critical infrastructure that needs test coverage.

• [ ] Examine cmd/limactl/hostagent.go and identify networking coordination logic
• [ ] Create pkg/hostagent/network_test.go for unit tests covering port mapping scenarios
• [ ] Add tests for vsock connection handling (github.com/mdlayher/vsock dependency)
• [ ] Add tests for DNS resolution and network translation (miekg/dns dependency usage)
• [ ] Add tests for TCP proxy routing (inetaf/tcpproxy dependency usage)

Add validation and schema tests for .lima config files

The repo uses invopop/jsonschema for schema generation (genschema.go) and invopop/jsonschema package, but there are no visible tests validating actual Lima config files against generated schemas. This would catch configuration regressions early and help new contributors understand the config file format.

• [ ] Create pkg/config/schema_test.go for validating Lima YAML configs
• [ ] Add test fixtures in pkg/config/testdata/ with valid and invalid config examples (default.yml variants, WSL2 configs, nested mount configs)
• [ ] Add tests validating that generated schema in cmd/limactl/genschema.go correctly validates real config files
• [ ] Add tests for edge cases: missing required fields, invalid driver combinations, mount path collisions
• [ ] Document config examples in generated schema output for contributors

• Add integration tests for cmd/lima-driver-wsl2/main_windows.go (currently Windows driver lacks comprehensive test coverage compared to QEMU/vz drivers). Test VM creation, file mounting, and port forwarding on Windows.
• Document the YAML schema for lima.yaml configs (likely generated from pkg/config structs but no schema.json file visible in top 60). Create a JSON Schema file and reference it in docs for IDE autocomplete.
• Add support for custom DNS servers in cmd/lima-guestagent/ (gvisor-tap-vsock can already handle DNS, but the config and CLI flag may be missing). Grep for 'DNS' in pkg/ and wire up a --dns-servers flag to limactl.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.